MCP servers

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

Verified

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.

curl -sL https://agentgateway.dev/install | bash

Steps

Step 1: Create the configuration

Create a config.yaml that defines an MCP target for the server-everything test server. This configuration uses the simplified MCP format.

cat > config.yaml << 'EOF'
# yaml-language-server: $schema=https://agentgateway.dev/schema/config

mcp:
  port: 3000
  targets:
  - name: server-everything
    stdio:
      cmd: npx
      args:
      - -y
      - "@modelcontextprotocol/server-everything"
EOF

You can also connect to a remote MCP server by using the mcp transport instead of stdio:

mcp:
  port: 3000
  targets:
  - name: remote-mcp
    mcp:
      host: http://localhost:3005/mcp/

Step 2: Review the configuration

Inspect the file to see how the simplified mcp field defines the port and targets.

cat config.yaml

Review the following table to understand this configuration.

Field	Description
`mcp`	The top-level MCP configuration block that defines how agentgateway connects to MCP servers.
`port`	The port on which agentgateway listens for incoming MCP requests, such as `3000`. If not specified, a default port is used.
`targets`	A list of MCP targets to connect to. Each target defines an MCP server that agentgateway proxies requests to. At least one target is required.
`name`	A unique name for the MCP target, such as `server-everything`. This name identifies the target in logs and the UI.
`stdio`	Configuration for connecting to an MCP server via standard input/output. Use this for local MCP servers that run as a command. Contains `cmd` (the command to run) and `args` (arguments for the command). In this example, `npx` runs the `@modelcontextprotocol/server-everything` package.
`mcp`	Configuration for connecting to a remote MCP server via streamable HTTP. Use this for remote MCP servers. Contains `host` (the URL of the MCP server endpoint).

Step 3: Start agentgateway

Run agentgateway with the config file.

agentgateway -f config.yaml

Example output:

info  state_manager  loaded config from File("config.yaml")
info  app            serving UI at http://localhost:15000/ui
info  proxy::gateway started bind  bind="bind/3000"

Step 4: Explore the UI

Open the agentgateway UI on the default port 15000 in your browser.

Port: Review the listening port (3000).
Targets: Review the MCP target (server-everything).
Policies: Review configured policies.

You can change the target and port configurations in the UI. Any updates you make apply immediately without restarting agentgateway.

Step 5: Connect and list tools in the Playground

Go to the Playground.
In the Testing card, check the Connection URL (such as http://localhost:3000/) and click Connect. The UI connects to the MCP target and lists its tools.
Confirm that Available Tools shows tools from the server, such as echo or various get commands.

Step 6: Run a tool

In Available Tools, select the echo tool.
In the message field, enter a string, such as This is my first agentgateway setup.
Click Run Tool.
Check the Response card for the echoed message.