For the complete documentation index, see llms.txt. Markdown versions of all docs pages are available by appending .md to any docs URL.

Connect to MCP servers via streamable HTTP with automatic session management

Connect to an MCP server via streamable HTTP.

About streamable HTTP

Agentgateway automatically manages stateful MCP sessions when using HTTP-based transports. The session state (including backend pinning) is encoded in the session ID and persisted across requests, ensuring that subsequent tool calls in the same session are routed to the same backend server.

    sequenceDiagram
    participant Client
    participant Agentgateway
    participant MCP Server

    Client->>Agentgateway: initialize (no session)
    Agentgateway->>MCP Server: initialize
    MCP Server-->>Agentgateway: initialized
    Note over Agentgateway: Pin session to backend<br/>Encode state into session ID
    Agentgateway-->>Client: Mcp-Session-Id: encrypted-state-abc123
    
    Client->>Agentgateway: call_tool (with session ID)
    Note over Agentgateway: Decode session ID<br/>Route to pinned backend
    Agentgateway->>MCP Server: call_tool (same server)
    MCP Server-->>Agentgateway: tool result
    Agentgateway-->>Client: result
  

1. Session initialization: When a client sends an initialize request, agentgateway creates a session and returns a session ID
2. Backend pinning: The session is pinned to a specific backend server (important when using multiple targets)
3. State encoding: The session state is encoded into the session ID using AES-256-GCM encryption
4. Session resumption: Subsequent requests with the same session ID are automatically routed to the same backend

Stateless sessions

By default, agentgateway proxies streamable HTTP in stateful mode, as described in the previous section. You can instead run in stateless mode with the statefulMode field, so that agentgateway does not create a session or return an Mcp-Session-Id header. Each request is treated independently, and the client must send the full context that the request needs. This mode suits stateless agents, or MCP servers where the client handles state directly.

To use stateless mode, set statefulMode to stateless on the MCP configuration.

# yaml-language-server: $schema=https://agentgateway.dev/schema/config
mcp:
  port: 3000
  statefulMode: stateless
  targets:
  - name: mcp
    mcp:
      host: http://localhost:3005/mcp/

When you send an initialize request through agentgateway in stateless mode, the response returns HTTP 200 with no Mcp-Session-Id header. In the default stateful mode, the same request returns an Mcp-Session-Id header that pins the session to a backend.

DNS rebinding protection

A browser page on any origin can resolve a hostname it controls to 127.0.0.1 and then send requests to a locally bound server. This is a DNS rebinding attack, and it is why the MCP specification requires a server that listens on localhost to reject a Host or Origin header that does not name a loopback address.

Agentgateway is usually a proxy in front of other servers rather than a browser-facing localhost server, so this check is off by default. Turn it on with dnsRebindingProtection when you run agentgateway on a developer machine and a browser can reach the MCP port.

# yaml-language-server: $schema=https://agentgateway.dev/schema/config
mcp:
  port: 3000
  dnsRebindingProtection: true
  targets:
  - name: mcp
    mcp:
      host: http://localhost:3005/mcp/

When the check is on, agentgateway applies the following rules.

A request that fails any rule receives a 403 response with the body MCP DNS rebinding protection: Host/Origin must be localhost, 127.0.0.1, or [::1].

Before you begin

Configure the agentgateway

1. Spin up an MCP server that uses streamable HTTP.

   PORT=3005 npx -y @modelcontextprotocol/server-everything streamableHttp

2. Create a configuration for your agentgateway to connect to your MCP server. Make sure to expose the Mcp-Session-Id header in the CORS configuration for session persistence.

   cat <<EOF > config.yaml
   # yaml-language-server: $schema=https://agentgateway.dev/schema/config
   mcp:
     port: 3000
     policies:
       cors:
         allowOrigins:
           - "*"
         allowHeaders:
           - "*"
         exposeHeaders:
           - "Mcp-Session-Id"
     targets:
     - name: mcp
       mcp:
         host: http://localhost:3005/mcp/
   EOF

3. Run the agentgateway.

   agentgateway -f config.yaml

Verify access to tools

1. Open the agentgateway UI to view your listener and backend configuration.

2. Connect to the MCP test server with the agentgateway UI playground.

   1. From the navigation menu under MCP, click Tool Playground.

   2. If you see a Browser access is not allowed notice, click Apply CORS so the playground can call the MCP listener from the UI.

   3. Click Initialize to open an MCP session. The agentgateway UI connects to the target that you configured and lists the tools that are exposed on the target.

      

      

3. Verify access to a tool.

   1. From the Tool list, select the echo tool.

   2. In the Message field, enter any string, such as This is my first agentgateway setup., and click Call tool.

   3. Verify that the Result card shows an HTTP 200 response with your message echoed back.