> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/agentgateway/agentgateway/llms.txt
> Use this file to discover all available pages before exploring further.

# 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.

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

## 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

<Tip>
  You can skip building from source entirely by using a pre-built binary or Docker. See [Installation](/installation) for all options.
</Tip>

## Run the basic MCP proxy

<Steps>
  <Step title="Install Agentgateway">
    Build and install Agentgateway from source. First, build the UI, then compile the binary.

    ```bash theme={null}
    # 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`.

    <Tip>
      Prefer a faster path? See [Installation](/installation) for pre-built binaries and Docker.
    </Tip>
  </Step>

  <Step title="Create your config file">
    Create a `config.yaml` file in your working directory. The following config is taken directly from the [basic example](https://github.com/agentgateway/agentgateway/tree/main/examples/basic):

    ```yaml config.yaml theme={null}
    # 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`

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

      ```yaml theme={null}
      stdio:
        cmd: docker
        args: ["run", "--rm", "-i", "mcp/everything"]
      ```
    </Note>
  </Step>

  <Step title="Run Agentgateway">
    Start the gateway, pointing it at your config file:

    <CodeGroup>
      ```bash Binary theme={null}
      ./target/release/agentgateway -f config.yaml
      ```

      ```bash cargo run theme={null}
      cargo run -- -f config.yaml
      ```
    </CodeGroup>

    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.
  </Step>

  <Step title="Connect with MCP Inspector">
    Use the [MCP Inspector](https://github.com/modelcontextprotocol/inspector) to verify your gateway is working:

    ```bash theme={null}
    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` |

    <Note>
      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.
    </Note>

    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.
  </Step>
</Steps>

## Understanding the configuration

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

<CardGroup cols={2}>
  <Card title="Binds" icon="network-wired">
    Each bind defines a port the gateway listens on. You can have multiple binds for different ports or protocols.
  </Card>

  <Card title="Listeners" icon="ear-listen">
    Listeners group routes within a bind. They can represent different virtual hosts, protocols, or tenant namespaces.
  </Card>

  <Card title="Routes" icon="route">
    Routes match incoming traffic and apply policies — such as CORS, authentication, or rate limiting — before forwarding to a backend.
  </Card>

  <Card title="Backends" icon="server">
    Backends define where traffic is sent. An MCP backend can aggregate multiple upstream MCP servers into a single endpoint.
  </Card>
</CardGroup>

For a full description of each field, see the [Configuration Reference](/reference/overview).

## Next steps

<CardGroup cols={2}>
  <Card title="Installation" icon="download" href="/installation">
    Install via pre-built binary, Docker, or build from source with all options.
  </Card>

  <Card title="MCP Proxy Guide" icon="plug" href="/guides/mcp-proxy">
    Add authentication, authorization, and observability to your MCP proxy.
  </Card>

  <Card title="Configuration reference" icon="file-code" href="/reference/overview">
    Explore the full configuration schema for binds, listeners, routes, and backends.
  </Card>

  <Card title="A2A Proxy Guide" icon="arrows-left-right" href="/guides/a2a-proxy">
    Connect AI agents to each other using the Agent2Agent protocol.
  </Card>
</CardGroup>