MCP servers

Verified : Code examples on this page have been automatically tested and verified.

Connect to an MCP server and try tools in the agentgateway playground.

Use the agentgateway binary to proxy requests to an open source MCP test server, server-everything. Then, try a tool in the built-in agentgateway playground.

Before you begin

Install the agentgateway binary.
Download and install the agentgateway binary. Alternatively, you can manually download the binary from the agentgateway releases page.
To install the latest release:
curl -sL https://agentgateway.dev/install | bash
Example output:
% Total % Received % Xferd Average Speed Time Time Time Current Dload Upload Total Spent Left Speed 100 8878 100 8878 0 0 68998 0 --:--:-- --:--:-- --:--:-- 69359 Downloading https://github.com/agentgateway/agentgateway/releases/download/v1.6.0/agentgateway-darwin-arm64 Verifying checksum... Done. Preparing to install agentgateway into /usr/local/bin Password: agentgateway installed into /usr/local/bin/agentgateway
To install a specific version, pass the --version flag. Use any release tag from the agentgateway releases page, such as v1.6.0. The version must start with v (the script adds the v if you omit it).
curl -sL https://agentgateway.dev/install | bash -s -- --version v1.6.0
A nightly build has no release tag and is not listed on the releases page. Instead, each nightly build is a run of the nightly GitHub Actions workflow, and you download the binary from that run’s artifacts.
1. Go to the nightly builds in GitHub Actions and click the run that you want to install from.
2. Copy the run ID from the end of that run’s URL, such as 24873456345 in https://github.com/agentgateway/agentgateway/actions/runs/24873456345.
3. Using the gh CLI, download the binary artifact for your OS. The following example uses macOS. For other operating systems, replace release-binary-mac with release-binary-linux, release-binary-linux-arm, or release-binary-windows.
  gh run download 24873456345 -R agentgateway/agentgateway -n release-binary-mac
4. Make the binary file executable and move it to your binary location, such as in the following example.
  chmod +x agentgateway sudo mv agentgateway /usr/local/bin/agentgateway
5. Verify that you have the nightly build. The version string of a nightly build is 0.0.0-alpha.<commit>, not a release tag.
  agentgateway --version
  Example output:
  { "version": "0.0.0-alpha.813d7d0", "git_revision": "813d7d0ab4757db7c8ed5a639bc63c0bb20ac116", "rust_version": "1.95.0", "build_profile": "release", "build_target": "aarch64-apple-darwin" }

Steps

Step 1: Start the MCP test server

Run the open source server-everything MCP test server with the streamable HTTP transport.

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

Step 2: Configure agentgateway

You can add the MCP server in the UI, or write it in a configuration file.

Because you add the MCP server from the UI, you can start agentgateway without a config file. When you run agentgateway without specifying a config, it bootstraps a basic config at ~/.config/agentgateway/config.yaml and uses it automatically.

Start agentgateway.

agentgateway

Example output:

info  app  serving UI at http://localhost:4000/ui

Open the agentgateway UI. The first time that you run the UI, the Welcome to Agentgateway wizard opens. Click Enable MCP, and then click Continue. If you already did this, skip to the next step.
The Gateway Overview home page opens, with the MCP row enabled.
Add the MCP server.
1. In the MCP section of the navigation menu, click Servers, and then click Add server.
2. For the Server name, enter server-everything.
3. Keep the Streamable HTTP transport. For the URL, enter http://localhost:3005/mcp.
4. Click Save server.

Create a configuration file with the MCP server as a target. The configuration also serves the UI on the same gateway, so that you can use the playground in the next step.

cat > config.yaml << 'EOF'
# yaml-language-server: $schema=https://agentgateway.dev/schema/config
gateways:
  default:
    port: 4000
mcp:
  targets:
  - name: server-everything
    mcp:
      host: http://localhost:3005/mcp
ui: {}
EOF

Start agentgateway with the configuration file.

agentgateway -f config.yaml

Example output:

info  app  serving UI at http://localhost:4000/ui

Step 3: Try a tool

You can try a tool in the UI playground or with curl. Both work the same way, whether you added the MCP server in the UI or in the config file.

In the agentgateway UI, click Tool Playground in the MCP section.
If you see a Browser access is not allowed notice, click Apply CORS so the playground can call the MCP listener from the UI.
Click Initialize to open an MCP session. The playground lists the tools that the server exposes, such as echo and various get commands.
From the Tool dropdown list, select the echo tool.
In the Message field, enter a string, such as This is my first agentgateway setup, and click Call tool.
Verify that the Result card shows an HTTP 200 response with your message echoed back.

Send MCP requests to the gateway with curl. The streamable HTTP transport uses JSON-RPC messages in POST requests. Each request needs the Accept: application/json, text/event-stream header. After you initialize a session, each request also needs the mcp-session-id header that agentgateway returns.

Initialize an MCP session, and save the session ID from the mcp-session-id response header. Then, send the notifications/initialized message to finish the handshake.

export MCP_SESSION_ID=$(curl -s -D - http://localhost:4000/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"curl","version":"1.0.0"}}}' \
  | grep -i "mcp-session-id:" | sed 's/.*: //' | tr -d '\r')
curl -s http://localhost:4000/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "mcp-session-id: $MCP_SESSION_ID" \
  -d '{"jsonrpc":"2.0","method":"notifications/initialized"}'

List the tools that the server exposes. The grep command prints only the tool names from the response.

curl -s http://localhost:4000/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "mcp-session-id: $MCP_SESSION_ID" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/list"}' \
  | grep -o '"name":"[^"]*"'

Example output:

"name":"echo"
"name":"get-annotated-message"
"name":"get-env"
"name":"get-resource-links"
"name":"get-resource-reference"
"name":"get-structured-content"
"name":"get-sum"
...

Call the echo tool with the message This is my first agentgateway setup.

curl -s http://localhost:4000/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "mcp-session-id: $MCP_SESSION_ID" \
  -d '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"echo","arguments":{"message":"This is my first agentgateway setup"}}}'

Verify that the response echoes your message back.

event: message
data: {"jsonrpc":"2.0","id":3,"result":{"content":[{"type":"text","text":"Echo: This is my first agentgateway setup"}]}}

Next steps

Check out more guides for using MCP servers with agentgateway.

stdioConnect to an MCP server via stdio Virtual MCPFederate multiple MCP servers. OpenAPIEnable OAuth 2.0 protection for MCP servers.

LLM Non-agentic HTTP traffic

Was this page helpful?

MCP servers

Before you begin

Steps

Step 1: Start the MCP test server

Step 2: Configure agentgateway

Step 3: Try a tool

Next steps

What could be improved?