MCP protocol

How the Agent Gateway handles Model Context Protocol traffic, including tool serving, 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.
  • Request LLM completions from the server side.

Transport is JSON-RPC 2.0 over HTTP/HTTPS. MCP also supports SSE (Server-Sent Events) streaming.

MCP surfaces

An MCP surface proxies all standard MCP JSON-RPC methods to a target tool server. These include initialize, tools/list, tools/call, resources/read, resources/list, prompts/get, and prompts/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.

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. An MCP proxy is linked to a surface using a mcp_proxy_id reference.

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.

Identity in MCP

The gateway can extract agent identity from MCP requests. Identity fields are placed in the _meta object of tool calls, using a configurable field name. The gateway reads this field and computes a DID for the agent, enabling the same identity lifecycle as other protocol types: DID assignment, VC issuance, and cross-gateway verification.