MCP Gateway

The MCP gateway exposes configured MCP servers through a unified route:

/v1/mcp/:identifier

The identifier can resolve to a configured server ID or slug.

MCP Server Model

An MCP server has:

• organisationId
• optional teamId
• optional apiKeyId
• name
• slug
• description
• transport: STREAMABLE_HTTP, SSE, or STDIO
• endpointUrl
• stdioCommand
• stdioArgs
• stdioEnv
• authType: NONE, BEARER, BASIC, OAUTH2
• authConfig
• oauthRequired
• enabled
• isPublic
• allowedTools
• blockedTools
• policies
• pricing
• semanticFilter
• rateLimit
• metadata

Transports

STREAMABLE_HTTP

The gateway proxies the MCP HTTP request to endpointUrl.

SSE

The gateway proxies to an SSE-capable endpoint and treats the request as streaming for rate-limit and observability metadata.

STDIO

The gateway starts the configured command with args and env, exchanges JSON-RPC over stdio, and returns the response.

Use STDIO carefully. It runs a configured local command in the gateway runtime environment.

Access Flow

For every MCP request, the gateway:

1. Enforces request concurrency if configured.
2. Allows only GET and POST.
3. Checks database availability.
4. Assigns request ID and telemetry context.
5. Runs pre-auth rate limiting.
6. Authenticates the Odock API key.
7. Resolves the MCP server by path identifier.
8. Requires the server to be enabled.
9. Checks ApiKeyMcpAccess.
10. Resolves and enforces rate-limit policy.
11. Extracts JSON-RPC method and tool name when available.
12. Applies allowed and blocked tool lists.
13. Reserves budget/quota capacity.
14. Proxies the MCP request through the configured transport.
15. Reconciles rate-limit usage.
16. Settles budget/quota usage.
17. Records generic usage and MCP-specific sidecar usage.

Tool Guardrails

Allowed and blocked tool lists are enforced by server configuration.

Recommended pattern:

• leave allowedTools empty for broad access during setup,
• add blockedTools for known-dangerous tools,
• later invert to a strict allowedTools list for production keys.

MCP Rate Limits

MCP policies use the same policy envelope as LLM policies. MCP server policies are evaluated under MCP scope.

Example:

{
  "policies": {
    "ratelimit": {
      "requests": { "per_minute": 300 },
      "payload": { "max_request_bytes": 262144 },
      "concurrency": { "max": 10 }
    }
  }
}

MCP Pricing

MCP pricing is stored as JSON on the server row. The gateway estimates and records:

• call cost,
• input byte cost,
• output byte cost,
• total nanos USD.

The exact keys are interpreted by the current MCP pricing helper in the gateway route. Keep pricing snapshots in metadata if you need external reconciliation.

Calling An MCP Server

curl http://localhost:8080/v1/mcp/my-server-slug \
  -H "Authorization: Bearer $ODOCK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": "1",
    "method": "tools/call",
    "params": {
      "name": "search",
      "arguments": { "query": "odock" }
    }
  }'

Usage Records

MCP requests are visible in:

• generic usage records,
• MCP usage records,
• Grafana token/usage dashboards where configured,
• logs and traces under provider mcp.