Quickstart

Get Agentgateway running in minutes with a basic MCP proxy example.

This guide walks you through running Agentgateway as an MCP proxy using the basic example. You will have a working gateway forwarding MCP traffic in under five minutes.

This guide requires npx (Node.js 18+) to run the example MCP server. If you prefer Docker, see the alternative command in step 3.

Prerequisites

• Rust 1.86+ and cargo — for building from source
• npm 10+ — to run the example MCP server via npx
• Basic familiarity with YAML configuration files

You can skip building from source entirely by using a pre-built binary or Docker. See Installation for all options.

Run the basic MCP proxy

1. Install Agentgateway

   Build and install Agentgateway from source. First, build the UI, then compile the binary.

   # Build the UI
   cd ui && npm install && npm run build && cd ..
   
   # Build the binary (sets CARGO_NET_GIT_FETCH_WITH_CLI for private deps)
   export CARGO_NET_GIT_FETCH_WITH_CLI=true
   make build
   

   The compiled binary is placed at ./target/release/agentgateway.

   Prefer a faster path? See Installation for pre-built binaries and Docker.

2. Create your config file

   Create a config.yaml file in your working directory. The following config is taken directly from the basic example:

   config.yaml

   # yaml-language-server: $schema=https://agentgateway.dev/schema/config
   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"]
   

   This configuration:

   • Binds the gateway to port 3000
   • Defines a single listener with one route that accepts all traffic
   • Applies a CORS policy allowing browser-based MCP clients
   • Proxies traffic to the everything MCP server, launched via npx

   If you do not have npx available, you can run the server with Docker instead:

   stdio:
     cmd: docker
     args: ["run", "--rm", "-i", "mcp/everything"]
   
3. Run Agentgateway

   Start the gateway, pointing it at your config file:

   Binary

   ./target/release/agentgateway -f config.yaml
   

   When the gateway starts, it will launch the everything MCP server as a child process over stdio. The gateway is now listening on http://localhost:3000.

   You can also open the admin UI at http://localhost:15000/ui to inspect your running configuration.

4. Connect with MCP Inspector

   Use the MCP Inspector to verify your gateway is working:

   npx @modelcontextprotocol/inspector
   

   The inspector will print the local URL it’s running on. Open it in your browser, then configure the connection:

   Setting	Value
   Transport	SSE or Streamable HTTP
   URL	http://localhost:3000/sse or http://localhost:3000/mcp

   Agentgateway exposes two MCP transport endpoints:

   • SSE at /sse — Server-Sent Events transport (MCP spec §transport)
   • Streamable HTTP at /mcp — newer bidirectional HTTP transport

   Both transports connect to the same backend. Use whichever your client supports.

   Once connected, navigate to the Tools tab in the inspector to see the tools exposed by the everything server. Try calling everything:echo — the gateway will proxy the request and return the response.

Understanding the configuration

The basic config introduces the four core building blocks of every Agentgateway configuration:

Binds

Each bind defines a port the gateway listens on. You can have multiple binds for different ports or protocols.

Listeners

Listeners group routes within a bind. They can represent different virtual hosts, protocols, or tenant namespaces.

Routes

Routes match incoming traffic and apply policies — such as CORS, authentication, or rate limiting — before forwarding to a backend.

Backends

Backends define where traffic is sent. An MCP backend can aggregate multiple upstream MCP servers into a single endpoint.

For a full description of each field, see the Configuration Reference.

Next steps

Installation

Install via pre-built binary, Docker, or build from source with all options.

MCP Proxy Guide

Add authentication, authorization, and observability to your MCP proxy.

Configuration reference

Explore the full configuration schema for binds, listeners, routes, and backends.

A2A Proxy Guide

Connect AI agents to each other using the Agent2Agent protocol.