Streamable HTTP Transport
Connect agentgateway to MCP servers via HTTP with streaming
Streamable HTTP transport connects agentgateway to remote MCP servers over HTTP with streaming support for real-time responses.
Overview
Streamable HTTP transport is ideal when:
- MCP servers run as standalone HTTP services
- You need real-time streaming of responses
- The server is accessible over the network
- You want stateful sessions with the MCP server
Quick start
# Start an MCP server with streamable HTTP
PORT=3005 npx -y @modelcontextprotocol/server-everything streamableHttp
# Create config.yaml
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
# Run agentgateway
agentgateway -f config.yaml
Configuration
Configure a streamable HTTP MCP backend:
# yaml-language-server: $schema=https://agentgateway.dev/schema/config
mcp:
port: 3000
policies:
cors:
allowOrigins:
- "*"
allowHeaders:
- "*"
exposeHeaders:
- "Mcp-Session-Id"
targets:
- name: remote-mcp
mcp:
host: http://mcp-server:8080/mcp/
Key configuration
| Setting | Description |
|---|---|
mcp.host | The HTTP URL of the MCP server endpoint |
cors.exposeHeaders | Must include Mcp-Session-Id for session management |
Example: Multiple MCP servers
Aggregate multiple remote MCP servers:
mcp:
port: 3000
targets:
- name: server-a
mcp:
host: http://mcp-server-a:8080/mcp/
- name: server-b
mcp:
host: http://mcp-server-b:8080/mcp/
Why use agentgateway?
| Direct HTTP Connection | With agentgateway |
|---|---|
| Client manages connections | Gateway handles reconnection and buffering |
| No authentication | OAuth2, API keys, or custom auth |
| No access control | Tool-level authorization |
| Single server per client | Multiple servers aggregated |
| No metrics | Full observability with OpenTelemetry |
| Manual session handling | Automatic session management |
Verify access
- Open the agentgateway UI to view your configuration
- Go to Playground to test tools
- Click Connect to retrieve available tools from all configured servers
- Select a tool and click Run Tool to test