Model Context Protocol (MCP)

This gateway exposes a small, implementation-driven MCP surface for health checks and knowledge base access.

There are currently 4 MCP tools in the public gateway.

There is currently no active auth-whoami or auth-verify-key MCP tool in the current gateway.

Overview

Authentication

MCP sessions are authenticated on connection by gateway middleware.

Accepted auth headers

Authenticate using one of the following headers:

• x-api-key: <your-api-key>
• x-access-key: <your-api-key>
• Authorization: Bearer <your-api-key>

Header priority is:

1. x-api-key
2. x-access-key
3. Authorization: Bearer <token>

If multiple values are present, the gateway uses the first non-empty header in that order.

Session behavior

• Initial MCP connection auth verifies the key through the Access Keys Manager.
• Requests with an existing session id reuse that session and do not re-verify the token on every request.
• Invalid or missing session ids return 401 Invalid or missing sessionId.

Authentication errors

Knowledge-base tool auth uses these exact error messages:

• Missing token: Missing API key
• Invalid token: Invalid API key

Response And Error Format

Successful tool responses are returned as MCP content with a single text item.

For structured results, the gateway serializes the upstream payload as pretty-printed JSON:

{
  "content": [
    {
      "type": "text",
      "text": "{\n  \"...\": \"...\"\n}"
    }
  ]
}

Validation failures return MCP tool errors with:

• isError: true
• a single text content item
• serialized zod flatten() output as JSON

Upstream Knowledge Base service failures are surfaced by the gateway as HTTP/MCP errors.

Tool Summary

search-knowledge-base

Purpose

Semantic vector search over the knowledge base using natural language queries.

Auth

Required.

Input schema

Behavior

• Verifies tenant from MCP auth headers
• Validates input with zod
• Forwards the validated search request to the Knowledge Base retrieval API
• Sends this body upstream:
  • namespace
  • query
  • topK
  • metadata when provided

This tool uses the RAG retrieval model to search the vector database and return the most relevant matches.

Example request

{
  "name": "search-knowledge-base",
  "arguments": {
    "namespace": "products",
    "query": "Find pressure washer models under 2000 PSI",
    "topK": 5,
    "metadata": {
      "category": "washers"
    }
  }
}

Example response

{
  "content": [
    {
      "type": "text",
      "text": "[\n  {\n    \"id\": \"...\",\n    \"score\": 0.91,\n    \"metadata\": {}\n  }\n]"
    }
  ]
}

Possible errors

• Missing API key
• Invalid API key
• Validation errors returned as isError: true with serialized flattened Zod output
• Upstream Knowledge Base service errors

get-entity

Purpose

Retrieve a full knowledge base entity by id or exact name.

Auth

Required.

Input schema

Validation rule:

• At least one of id or name must be provided

Behavior

• Verifies tenant from MCP auth headers
• Validates input with zod
• Uses id if present, otherwise name
• URL-encodes the selected key
• Uses the public Knowledge Base entity endpoint: GET /knowledge-base/entities/{idOrAlias}

Example request

{
  "name": "get-entity",
  "arguments": {
    "id": "68dfc8fd5e40fe1ae99c6b5b"
  }
}

Example response

{
  "content": [
    {
      "type": "text",
      "text": "{\n  \"_id\": \"68dfc8fd5e40fe1ae99c6b5b\",\n  \"name\": \"Example Entity\"\n}"
    }
  ]
}

Possible errors

• Missing API key
• Invalid API key
• Validation error if both id and name are missing
• Upstream Knowledge Base service errors

get-knowledge-base-structure

Purpose

Browse the knowledge base category tree (optionally drill into a category).

Auth

Required.

Input schema

Behavior

• Verifies tenant from MCP auth headers
• Validates input with zod
• If categoryId is provided, it maps to: GET /knowledge-base/categories/{key}
• Otherwise it maps to: GET /knowledge-base/categories

Example request

{
  "name": "get-knowledge-base-structure",
  "arguments": {
    "categoryId": "68dfc8fd5e40fe1ae99c6b5b"
  }
}

Example response

{
  "content": [
    {
      "type": "text",
      "text": "{\n  \"_id\": \"68dfc8fd5e40fe1ae99c6b5b\",\n  \"name\": \"Support Policies\",\n  \"children\": []\n}"
    }
  ]
}

Possible errors

• Missing API key
• Invalid API key
• Validation errors returned as isError: true with serialized flattened Zod output
• Upstream Knowledge Base service errors

Notes

• Knowledge-base tools rely on tenant resolution from auth headers and upstream Knowledge Base proxying.
• Successful responses are text-wrapped JSON, not native structured MCP objects.
• Validation errors are returned as MCP errors with serialized Zod flatten output.
• The currently exposed MCP surface is intentionally small and includes only the 4 tools documented on this page.