> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/agentgateway/agentgateway/llms.txt
> Use this file to discover all available pages before exploring further.

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

<Tabs>
  <Tab title="MCP">
    ## Model Context Protocol (MCP)

    [Model Context Protocol](https://modelcontextprotocol.io/introduction) 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

    <CardGroup cols={2}>
      <Card title="Protocol translation" icon="arrows-left-right">
        Transparently proxy MCP requests between any combination of transports — SSE, Streamable HTTP, or Stdio.
      </Card>

      <Card title="Authentication" icon="key">
        Enforce JWT, API key, or mTLS authentication before MCP requests reach backend servers.
      </Card>

      <Card title="Tool-level authorization" icon="shield">
        Use CEL expressions to allow or deny access to specific MCP tools, resources, or prompts by name.
      </Card>

      <Card title="Aggregation" icon="layer-group">
        Expose multiple upstream MCP servers as a single MCP endpoint with merged tool lists.
      </Card>
    </CardGroup>

    ### MCP transports

    MCP supports three transport mechanisms. Agentgateway handles all three.

    <AccordionGroup>
      <Accordion title="Streamable HTTP (/mcp)" icon="globe" defaultOpen={true}>
        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.

        ```yaml theme={null}
        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.
      </Accordion>

      <Accordion title="SSE (/sse)" icon="bolt">
        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.

        ```yaml theme={null}
        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
        ```
      </Accordion>

      <Accordion title="Stdio" icon="terminal">
        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.

        ```yaml theme={null}
        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.

        <Note>
          Stdio backends are started when the configuration is loaded and restarted automatically if the process exits.
        </Note>
      </Accordion>
    </AccordionGroup>

    ### MCP backend configuration

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

    ```yaml theme={null}
    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.

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

  <Tab title="A2A">
    ## Agent2Agent (A2A)

    [Agent2Agent (A2A)](https://developers.googleblog.com/en/a2a-a-new-era-of-agent-interoperability/) 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.

    ```yaml theme={null}
    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:

    ```yaml theme={null}
    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
    ```

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

  <Tab title="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:

    ```yaml theme={null}
    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:

    ```yaml theme={null}
    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
    ```

    <Tip>
      You can run MCP, A2A, and HTTP routes on the same port and listener. The gateway dispatches traffic based on route matching rules.
    </Tip>
  </Tab>
</Tabs>

## 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`                          |

<CardGroup cols={2}>
  <Card title="MCP proxy guide" icon="plug" href="/guides/mcp-proxy">
    Step-by-step guide to proxying MCP servers with authentication and authorization
  </Card>

  <Card title="A2A proxy guide" icon="arrows-left-right" href="/guides/a2a-proxy">
    Set up agent-to-agent communication with the A2A protocol
  </Card>

  <Card title="OpenAPI guide" icon="code" href="/guides/openapi">
    Transform REST APIs into MCP tools using OpenAPI specifications
  </Card>

  <Card title="CEL expressions" icon="filter" href="/concepts/cel-expressions">
    Write tool-level authorization rules using CEL expressions
  </Card>
</CardGroup>