Protocols

How Agentgateway proxies MCP, A2A, and HTTP traffic — including transports, agent card rewriting, and OpenAPI-to-MCP transformation.

Agentgateway provides first-class support for three protocols: MCP (Model Context Protocol) for agent-to-tool communication, A2A (Agent2Agent) for agent-to-agent communication, and HTTP for generic web traffic. Each protocol has dedicated handling optimized for its semantics.

MCP

Model Context Protocol (MCP)

Model Context Protocol is the standard for connecting AI agents to tools, resources, and prompts. Agentgateway acts as an MCP proxy: it receives MCP requests from clients (AI agents), applies policies, and forwards them to one or more upstream MCP servers.

What Agentgateway provides for MCP

Protocol translation

Transparently proxy MCP requests between any combination of transports — SSE, Streamable HTTP, or Stdio.

Authentication

Enforce JWT, API key, or mTLS authentication before MCP requests reach backend servers.

Tool-level authorization

Use CEL expressions to allow or deny access to specific MCP tools, resources, or prompts by name.

Aggregation

Expose multiple upstream MCP servers as a single MCP endpoint with merged tool lists.

MCP transports

MCP supports three transport mechanisms. Agentgateway handles all three.

Streamable HTTP (/mcp)

The modern MCP transport, introduced in the MCP specification. Clients POST requests to /mcp and receive streaming responses. This is the recommended transport for new deployments.

backends:
- mcp:
    targets:
    - name: my-server
      # Streamable HTTP upstream
      host: mcp-server:8080

Clients connect by sending POST /mcp with a Content-Type: application/json body.

SSE (/sse)

The original MCP transport using Server-Sent Events. The client connects to /sse to establish a persistent event stream, then sends requests via POST /message.

SSE is supported for backwards compatibility with existing MCP clients. The Mcp-Session-Id header tracks sessions across the SSE connection.

routes:
- policies:
    cors:
      allowOrigins: ["*"]
      allowHeaders:
      - mcp-protocol-version
      - content-type
      - cache-control
      exposeHeaders:
      - "Mcp-Session-Id"
  backends:
  - mcp:
      targets:
      - name: my-server
        host: mcp-server:8080

Stdio

Agentgateway can spawn MCP servers as child processes and communicate with them over stdin/stdout. This is useful for running local MCP servers (e.g., Node.js MCP packages) without requiring them to bind to a network port.

backends:
- mcp:
    targets:
    - name: everything
      stdio:
        cmd: npx
        args: ["@modelcontextprotocol/server-everything"]

The cmd is the executable to run. args are passed as command-line arguments. The process inherits the gateway’s environment.

Stdio backends are started when the configuration is loaded and restarted automatically if the process exits.

MCP backend configuration

The mcp backend accepts a list of targets. Each target represents one upstream MCP server.

backends:
- mcp:
    targets:
    - name: my-server          # Name used in logs and CEL context
      stdio:                   # or: host: mcp-server:8080
        cmd: npx
        args: ["@modelcontextprotocol/server-everything"]

Multiple targets are aggregated: the gateway merges their tool lists and routes MCP calls to the correct upstream based on the tool name.

OpenAPI-to-MCP transformation

Agentgateway can transform legacy REST APIs into MCP-compatible tool servers using an OpenAPI specification. This allows AI agents to call existing HTTP APIs through MCP without any changes to the underlying service.

When configured, the gateway reads the OpenAPI spec and exposes each operation as an MCP tool. The tool name, description, and input schema are derived from the OpenAPI operation definition.

OpenAPI-to-MCP transformation lets you give AI agents access to your existing REST APIs through the MCP protocol — without modifying the APIs themselves.

A2A

Agent2Agent (A2A)

Agent2Agent (A2A) is a protocol for communication between AI agents from different frameworks or vendors. Agentgateway proxies A2A traffic and adds security and observability to agent-to-agent interactions.

Enabling A2A on a route

A2A is enabled per-route using the a2a: {} policy marker. This tells the gateway to treat the route as A2A traffic and apply A2A-specific handling.

binds:
- port: 3000
  listeners:
  - routes:
    - policies:
        cors:
          allowOrigins: ['*']
          allowHeaders:
          - content-type
          - cache-control
        # Mark this route as A2A traffic
        a2a: {}
      backends:
      - host: localhost:9999

Agent card rewriting

A2A agents advertise their capabilities through an agent card served at /.well-known/agent.json. When Agentgateway proxies A2A traffic, it automatically intercepts requests to this endpoint and rewrites the agent card.

The rewritten agent card reflects the gateway’s address rather than the upstream agent’s address. This ensures that:

• Clients discover the correct endpoint (the gateway) for all subsequent communication
• The upstream agent’s internal address is never exposed to external clients
• Security policies enforced by the gateway apply to all traffic, including capability discovery

Client
  │  GET /.well-known/agent.json
  ▼
Agentgateway
  │  Rewrites serviceUrl to gateway's public address
  │  GET /.well-known/agent.json  (forwarded to upstream)
  ▼
Upstream A2A agent

A2A with access logging

The A2A example shows how to combine A2A proxying with structured access logging using a CEL expression:

config:
  logging:
    format: json
frontendPolicies:
  accessLog:
    add:
      backend: backend   # Log the backend name for each request
binds:
- port: 3000
  listeners:
  - routes:
    - policies:
        a2a: {}
      backends:
      - host: localhost:9999

frontendPolicies applies policies globally to all traffic entering the gateway, before route matching. This is useful for universal access logging or global authentication.

HTTP

HTTP

Agentgateway supports generic HTTP/1.1 and HTTP/2 traffic for cases where you need to proxy standard web services alongside MCP or A2A endpoints.

HTTP routing

HTTP routes support rich matching on path, headers, method, and query parameters:

routes:
- matches:
  - path:
      pathPrefix: /api/v1
    method: GET
  - path:
      pathPrefix: /api/v1
    method: POST
  - headers:
    - name: x-internal
      value:
        exact: "true"
  backends:
  - host: api-service:8080

Supported path match types:

Type	Field	Example
Exact	exact	/api/v1/users
Prefix	pathPrefix	/api/
Regex	regex	/api/v[0-9]+/.*

Supported header match types:

Type	Field	Example
Exact	exact	Bearer token123
Regex	regex	Bearer .*

TLS termination

Agentgateway terminates TLS at the listener level:

binds:
- port: 443
  listeners:
  - hostname: api.example.com
    tls:
      cert: /certs/tls.crt
      key: /certs/tls.key
      minTLSVersion: "1.2"
      maxTLSVersion: "1.3"
    routes:
    - backends:
      - host: api-service:8080

You can run MCP, A2A, and HTTP routes on the same port and listener. The gateway dispatches traffic based on route matching rules.

Protocol summary

Protocol	Transport	Gateway endpoint	Backend type
MCP	Streamable HTTP	POST /mcp	mcp.targets[].host or stdio
MCP	SSE	GET /sse + POST /message	mcp.targets[].host or stdio
A2A	HTTP	All paths	host with a2a: {} policy
HTTP	HTTP/1.1, HTTP/2	Configurable paths	host

MCP proxy guide

Step-by-step guide to proxying MCP servers with authentication and authorization

A2A proxy guide

Set up agent-to-agent communication with the A2A protocol

OpenAPI guide

Transform REST APIs into MCP tools using OpenAPI specifications

CEL expressions

Write tool-level authorization rules using CEL expressions