MCP servers

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

Install Node.js to run the MCP server via npx.

Steps

Step 1: Download a basic configuration

Download the basic MCP example configuration.

curl -L https://agentgateway.dev/examples/basic/config.yaml -o config.yaml

Step 2: Review the configuration

Inspect the file to see how the listener, route, and MCP backend are defined.

cat config.yaml

config.yaml

binds:
- port: 3000
  listeners:
  - routes:
    - policies:
        cors:
          allowOrigins:
          - "*"
          allowHeaders:
          - mcp-protocol-version
          - content-type
          - cache-control
          exposeHeaders:
          - "Mcp-Session-Id"
      backends:
      - mcp:
          targets:
          - name: everything
            stdio:
              cmd: npx
              args: ["@modelcontextprotocol/server-everything"]

Review the following table to understand this configuration.

Field	Description
`binds`	Binds set up each port on which the agentgateway listens for incoming requests. This example configures one port.
`port`	The port to listen on, such as `3000`.
`listeners`	Listeners configure how agentgateway accepts and processes incoming requests. They do this by grouping together resources such as routes and the backends that serve traffic.
`routes`	Routes configure advanced routing features, such as traffic policies, that control how traffic is sent to the backends. In the example, the route matches all traffic.
`policies`	Policies configure traffic policies on routes that shape how traffic is sent to the backends. In the example, a basic CORS policy is configured to allow all origins and the `mcp-protocol-version` header. This way, the configuration works with the MCP inspector tool.
`backends`	Backends configure the backing destination where the traffic is sent to. Backends can be MCP servers, A2A agents, or OpenAPI servers. In this example, the backend is an MCP server.
`targets`	Targets configure the details of the backend, such as the MCP server. In this example, the target is the sample, open source MCP test server, `server-everything`. The server runs a bunch of tools in a single process that are useful for testing.
`stdio`	To run the server, you use the standard input/output (`stdio`) capability of the agentgateway, which allows you to pass in the command and command arguments that you want to use. In this example, the `npx` command is used. The `npx` command utility lets you run a Node.js package (`@modelcontextprotocol/server-everything`) without installing it. If you do not have `npx` on your machine, follow the instructions to install Node.js.

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.

Listeners: Review the listener on port 3000.
Routes: Review the route for the MCP backend.
Backends: Review the MCP target (server-everything).
Policies: Review route and backend policies.

You can change listener, route, and backend configuration 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.