stdio Transport
The stdio transport connects Agent Gateway to MCP servers that run as local processes, communicating via standard input/output.
Overview
stdio transport is ideal when:
- MCP servers run as local command-line tools
- You want to manage MCP server lifecycle with Agent Gateway
- The server is distributed as an npm package or binary
Quick start
# Download the stdio MCP configuration
curl -L https://raw.githubusercontent.com/agentgateway/agentgateway/refs/heads/main/examples/basic/config.yaml -o config.yaml
# Run Agent Gateway
agentgateway -f config.yamlConfiguration
Configure an stdio MCP backend in your config.yaml:
binds:
- port: 3000
listeners:
- routes:
- policies:
cors:
allowOrigins:
- "*"
allowHeaders:
- "*"
exposeHeaders:
- "Mcp-Session-Id"
backends:
- mcp:
targets:
- name: my-mcp-server
stdio:
cmd: npx
args:
- "-y"
- "@modelcontextprotocol/server-everything"Example: MCP test server
The MCP test server (@modelcontextprotocol/server-everything) is useful for testing:
backends:
- mcp:
targets:
- name: test-server
stdio:
cmd: npx
args:
- "-y"
- "@modelcontextprotocol/server-everything"Example: Filesystem MCP server
Expose local filesystem access via MCP:
backends:
- mcp:
targets:
- name: filesystem
stdio:
cmd: npx
args:
- "-y"
- "@modelcontextprotocol/server-filesystem"
- "/path/to/allowed/directory"Why use Agent Gateway?
| Direct stdio | With Agent Gateway |
|---|---|
| One client per server | Multiple clients share servers |
| No authentication | OAuth2, API keys, or custom auth |
| No access control | Tool-level authorization |
| Client manages process | Gateway manages lifecycle |
| No metrics | Full observability with OpenTelemetry |
Verify access
- Open the Agent Gateway UI to view your configuration
- Go to Playground to test tools
- Click Connect to retrieve available tools
- Select a tool and click Run Tool to test