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.

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 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.