MCP Gateway

Overview

The MCP Gateway is a single JSON-RPC 2.0 endpoint. It authenticates the caller's mcp_ key, enforces scopes and agency/location access, then proxies the call to a registered upstream MCP server, injecting that client's credentials.

Endpoint

POST https://mythic-analytics.gulp.workers.dev/mcp

The endpoint accepts a single JSON-RPC request object per HTTP call. CORS is open (*) for POST and OPTIONS.

Authentication

Send the mcp_ key as a bearer token or in X-Api-Key.

Authorization: Bearer mcp_...

See Authentication for scope rules.

JSON-RPC 2.0 format

Request

{
  "jsonrpc": "2.0",
  "id": "req-001",
  "method": "tools/call",
  "params": {
    "name": "an_upstream_tool",
    "arguments": { "limit": 10 }
  }
}

Success response

{
  "jsonrpc": "2.0",
  "id": "req-001",
  "result": {
    "content": [
      { "type": "text", "text": "[ ... insights ... ]" }
    ]
  }
}

Error response

{
  "jsonrpc": "2.0",
  "id": "req-001",
  "error": {
    "code": -32601,
    "message": "Method not found: tools/execute"
  }
}

Protocol versions

The gateway supports 2024-11-05, 2025-03-26, 2025-06-18, and 2025-11-25. It answers initialize with the version you requested when it is one of those, and with 2025-11-25 otherwise.

If you send the MCP-Protocol-Version header on post-handshake requests (required of clients from 2025-06-18 onward), it must name one of the supported versions — anything else is rejected with 400 and error code -32600. Omitting the header is accepted.

The 2026-07-28 revision (stateless requests, _meta version negotiation, MRTR) is not yet served; clients that speak it should fall back to 2025-11-25, which server/discover advertises.

Methods

server/discover

Returns supported protocol versions, capabilities, and server identity in a single request. No handshake required — you may call it before anything else.

{ "jsonrpc": "2.0", "id": 1, "method": "server/discover", "params": {} }

Result:

{
  "resultType": "complete",
  "supportedVersions": ["2024-11-05", "2025-03-26", "2025-06-18", "2025-11-25"],
  "capabilities": { "tools": {} },
  "instructions": "Mythic Analytics gateway: per-client analytics and upstream MCP tools, scoped by the mcp_ API key.",
  "ttlMs": 3600000,
  "cacheScope": "private",
  "_meta": {
    "io.modelcontextprotocol/serverInfo": { "name": "mythic-analytics-gateway", "version": "1.0.0" }
  }
}

initialize

Returns protocol and server info. No authentication side effects beyond the standard key check.

{ "jsonrpc": "2.0", "id": 1, "method": "initialize", "params": { "protocolVersion": "2025-11-25" } }

Result:

{
  "protocolVersion": "2025-11-25",
  "capabilities": { "tools": {} },
  "serverInfo": { "name": "mythic-analytics-gateway", "version": "1.0.0" }
}

notifications/initialized

Client lifecycle notification. The gateway accepts it and returns an empty result.

tools/list

Returns every upstream tool the key can use, filtered by scope, agency access, and location access. Each entry has name, description, inputSchema, and annotations. Tools come back sorted by name, so the list is stable across calls and safe to cache. The result also carries ttlMs (300000) and cacheScope ("private") as caching hints.

{ "jsonrpc": "2.0", "id": 2, "method": "tools/list", "params": {} }

tools/call

Execute a tool by name.

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "an_upstream_tool",
    "arguments": { "query": "Q3 overview" }
  }
}

The result is the tool's MCP content payload ({ "content": [...] }, optionally with "isError": true), proxied through from the upstream server unchanged.

Tools

Every tool comes from a registered upstream server and requires the <scope_prefix>:call scope (or upstream:call when the server has no scope prefix).

Retired built-in tools

The gateway previously implemented list_insights, get_insight, create_insight, update_insight, delete_insight, list_dashboards, get_dashboard, create_dashboard, update_dashboard, delete_dashboard, add_insight_to_dashboard, remove_insight_from_dashboard, list_canvases, and get_canvas itself. These names now return -32601 with a message pointing at the Settings Server, which serves them (and many more) with the same mcp_ key.

Error codes

Standard JSON-RPC codes are used throughout:

Rate limiting

The gateway enforces a per-key, per-minute request ceiling using a sliding window. The limit comes from the key's rate_limit_per_minute (default 60). Exceeding it returns HTTP 429:

{ "jsonrpc": "2.0", "id": null, "error": { "code": -32000, "message": "Rate limit exceeded" } }