MCP protocol

How the Agent Gateway handles Model Context Protocol traffic across the 2024-11-05 and 2026-07-28 revisions, including transport, methods, agent identity, OpenAPI proxying, and tool-level access control.

MCP (Model Context Protocol) is Anthropic’s standard for exposing tools, resources, and prompts to AI models. The Agent Gateway supports MCP as a first-class protocol: it proxies MCP traffic to upstream tool servers and can convert REST APIs into MCP-compatible tool endpoints. Set up an MCP surface →

What MCP enables

MCP enables AI models and applications to:

  • Discover available tools with their schemas.
  • Execute tool invocations with structured parameters.
  • Read data sources and file-like resources.
  • Retrieve pre-built prompt templates.
  • Receive notifications when the server’s tools, prompts, or resources change.

MCP transport

MCP messages are JSON-RPC 2.0 over HTTP or HTTPS. The gateway serves both MCP protocol revisions, and each uses HTTP differently:

  • 2024-11-05: the client opens a session with initialize, and the Mcp-Session-Id header identifies the session on later requests. A response can stream back as Server-Sent Events (SSE), and the client can open a GET notification stream on the same URL. Clients that use the older SSE pattern, opening GET /sse and posting messages to a separate endpoint, also work through an Access Point, and MCP Proxies serve that pattern themselves.
  • 2026-07-28: each request is a self-contained POST, with no session and no initialize handshake. The request carries its protocol revision and client capabilities in params._meta, and repeats the revision and method in the MCP-Protocol-Version and Mcp-Method headers. A tools/call, prompts/get, or resources/read request also names its tool, prompt, or resource in the Mcp-Name header. The response is either JSON or an SSE stream, and a client that wants change notifications calls subscriptions/listen.

Between connected gateways, 2026-07-28 traffic travels as streamed Fabric messages. 2024-11-05 traffic travels as single forwarded requests, and a streamed response arrives at the caller as one final response.

MCP surfaces

An MCP surface forwards MCP JSON-RPC methods to its target tool server whatever their name, so a method the server adds reaches it with the gateway configuration unchanged. Common methods are tools/list, tools/call, resources/list, resources/read, prompts/list, and prompts/get.

The opening exchange depends on the revision. A 2024-11-05 client starts with initialize. A 2026-07-28 client calls server/discover instead, and the gateway narrows the result to the protocol revisions and capabilities the surface supports. A 2026-07-28 client receives change notifications by calling subscriptions/listen.

An MCP Proxy answers a smaller set of methods itself, because it serves tools generated from an OpenAPI specification:

  • 2024-11-05: initialize, tools/list, and tools/call.
  • 2026-07-28: server/discover, tools/list, tools/call, and subscriptions/listen for changes to its tool list.

The surface applies the same inbound and outbound processing as other surface types, including identity extraction, OPA policy evaluation, rate limiting, and metadata injection, before and after forwarding.

Which MCP protocol revisions the gateway accepts

Every MCP endpoint on the gateway accepts both MCP protocol revisions it supports, 2024-11-05 and 2026-07-28, with no setting to choose between them. This covers Access Points, Transit Points, MCP Proxies, and traffic between connected gateways over Fabric.

A client that opens a session with initialize and asks for a newer session-based revision, such as 2025-06-18 or 2025-11-25, can still connect. The gateway forwards the initialize asking for 2024-11-05 instead, and the session runs at 2024-11-05 when the client accepts it. This applies when the request carries no MCP-Protocol-Version header, or a header set to 2024-11-05.

When a request’s MCP-Protocol-Version header names a revision other than 2024-11-05 or 2026-07-28, the gateway refuses the request, an initialize included, with HTTP 400 and JSON-RPC error -32022 (Unsupported protocol version). The error’s data shows the revision the client requested and lists the two revisions the gateway supports. See Troubleshooting for which clients connect and how to resolve each error.

When a client sends a 2026-07-28 request to a surface whose upstream server supports only 2024-11-05, the gateway answers with HTTP 502, so pair 2026-07-28 clients with upstream servers that support that revision. An MCP Proxy serves both revisions itself. See MCP Proxy for the case where it can serve only 2026-07-28.

How the gateway checks each MCP request

Before tool gating, tool policies, or credential injection run, the gateway checks that each MCP request has a shape every component reads the same way. A request that fails a check is refused before it reaches the upstream server:

  • A POST body must be exactly one JSON-RPC object. Invalid JSON returns JSON-RPC error -32700, valid JSON other than an object returns -32600, and the gateway refuses a JSON-RPC batch.
  • Each key appears once per object, and keys that differ only in letter case count as the same key. Fields the gateway reads use their exact case, such as method and params.name rather than Method or params.Name. A body that breaks either rule returns -32600.
  • Access Points, Transit Points, and Fabric traffic accept the HTTP methods POST, GET, DELETE, HEAD, and OPTIONS. Any other method returns HTTP 405 with an Allow header listing them. A request with a body on any method other than POST returns HTTP 400 with -32600. A 2026-07-28 request uses POST only, so a GET or DELETE that declares that revision returns HTTP 405 with Allow: POST.
  • Legacy Server-Sent Events (SSE) sessions opened with GET /sse, on MCP Proxies and on surfaces whose target is an MCP Proxy or a connected gateway, are limited to 10,000 at once across the gateway. A request beyond that limit returns HTTP 429 with the message Too many active SSE sessions.

These checks keep tool gating and tool-scoped credentials reliable: the tool name the gateway checks is the same tool name the upstream server runs.

MCP proxies (OpenAPI to MCP)

The gateway can convert any REST API into an MCP-compatible tool server by importing its OpenAPI specification. This lets AI models call existing REST APIs as if they were MCP tools, without modifying the API.

The gateway parses the OpenAPI specification and generates MCP tool definitions for each API endpoint. Clients discover and call these tools via standard MCP protocol. A surface serves an MCP Proxy by using it as its target, with the via MCP Proxy endpoint type.

Tool-level access control

OPA Rego policies can be scoped to individual MCP methods and tool names. This allows fine-grained control over which agents or roles can call specific tools.

For example, a policy can allow all MCP methods except tools/call for specific tool names, while allowing administrator-role agents full access. Policy input includes the MCP method, tool name, surface context, and JWT claims if bearer authentication is configured.

Filtering MCP tools by pattern, not by name

The per-tool policies above bind one Rego rule to one exact tool name, which works well when the full set of tool names is known in advance and each one needs its own logic. That approach does not scale as well when many tools share a naming convention, or when a tool server adds new tools over time, because each new tool needs its own rule added by hand.

MCP Tool Gating solves this by matching tool names against a regex pattern instead of an exact name, so one allow or deny rule can cover a whole family of tools at once, and by making a rule conditional on an OPA policy rather than always active. Where per-tool policies ask “does this exact tool’s policy allow the call?”, MCP Tool Gating asks “does this tool name match a pattern, and, if the gate has a condition, does that condition currently hold?”.

For example, an MCP proxy generated from a large OpenAPI specification can expose dozens of similarly named tools. A single Deny gate with a pattern such as ^admin_.*$ hides every admin-prefixed tool without a policy per tool, and a Deny gate whose Condition checks the caller’s organisation claim can hide the same family only for external callers, leaving it visible internally.

See MCP Tool Gating element for the field-level reference, and Control MCP tool access with per-tool policies for configuring the exact-name mechanism.

Identity in MCP

The gateway can derive an agent’s identity from MCP requests. With the Identity element’s extraction type set to From Payload (identity metadata), the gateway reads the identity object from the request’s _meta, under the field named in Identity Meta Field Name (agentIdentity by default). It reads that field on every MCP request, tool calls included:

  • 2026-07-28: the identity object goes in params._meta.
  • 2024-11-05: the identity object goes in params._meta, or in a top-level _meta object for older clients.

The gateway hashes the payload fields you mark as identity fields into a DID for the agent, and that DID follows the same identity lifecycle as on other protocols. When the field is missing, the gateway refuses the request with HTTP 422. The Identity element can also derive identity From API Key or From JWT Claims, with no _meta field involved.