Documentation
Get started

Get started

Get started with agentgateway, an open source, highly available, and highly scalable data plane that brings AI connectivity for agents and tools. To learn more about agentgateway, see the About section.

About this guide

In this guide, you learn how to use the agentgateway to proxy requests to an open source MCP test server that exposes multiple MCP test tools.

You complete the following tasks:

  • Install the agentgateway binary on your local machine.
  • Create an agentgateway configuration that proxies requests to multiple tools that are exposed on an open source MCP test server, server-everything.
  • Explore the agentgateway UI.
  • Test access to the everything_echo MCP tool.

Step 1: Install the binary

  1. Download the agentgateway binary and install it.

    curl https://raw.githubusercontent.com/agentgateway/agentgateway/refs/heads/main/common/scripts/get-agentproxy | 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/v0.4.16/agentgateway-darwin-arm64
Verifying checksum... Done.
Preparing to install agentgateway into /usr/local/bin
Password:
agentgateway installed into /usr/local/bin/agentgateway

  2. Verify that the agentgateway binary is installed.

    agentgateway --version

    Example output with the latest version, 0.6.1:

    agentgateway-app version.BuildInfo{RustVersion:"1.88.0", BuildProfile:"release", BuildStatus:"Modified", GitTag:"v0.6.1", Version:"2c7ba0d4ed47fcafa97fa411fdbf1a8ca40cf6a9-dirty", GitRevision:"2c7ba0d4ed47fcafa97fa411fdbf1a8ca40cf6a9-dirty"}

Step 2: Create a basic configuration

In this example, you use a basic configuration file to configure the agentgateway, but you can also use the agentgateway UI to configure these components. For examples, see the Listeners and Backends guides.

  1. Download a basic configuration file for your agentgateway.

    curl -L https://raw.githubusercontent.com/agentgateway/agentgateway/refs/heads/main/examples/basic/config.yaml -o config.yaml

  2. Review the configuration file.

    cat config.yaml
    config.yaml
    binds:
- port: 3000
  listeners:
  - routes:
    - policies:
        cors:
          allowOrigins:
            - "*"
          allowHeaders:
            - mcp-protocol-version
            - content-type
      backends:
      - mcp:
          name: default
          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.

  3. Run the agentgateway.

    agentgateway -f config.yaml

    Example output:

    2025-04-16T20:19:36.449164Z  INFO agentgateway: Reading config from file: basic.yaml
2025-04-16T20:19:36.449580Z  INFO insert_target: agentgateway::xds: inserted target: everything
2025-04-16T20:19:36.449595Z  INFO agentgateway::r#static: local config initialized num_mcp_targets=1 num_a2a_targets=0
2025-04-16T20:19:36.449874Z  INFO agentgateway::inbound: serving sse on [::]:3000

Step 3: Explore the UI

The agentgateway comes with a built-in UI that you can use to connect to your MCP target to view and access the tools that are exposed on the MCP server. You can also use the UI to review and update your listener and target configuration in-flight. Configuration updates are available immediately and do not require a restart of the agentgateway.

  1. Open the built-in agentgateway UI.

  2. Go to the Listener overview and review your listener configuration. To learn how to create more or delete existing listeners with the UI, see the Listeners docs.

  3. Go to the Routes overview and review your route and policy configuration. To learn how to create more or delete existing routes with the UI, see the Routes docs.

  4. Go to the Backends overview and review your target configuration. To learn how to create more or delete existing targets with the UI, see the Backends docs.

  5. Go to the Policies overview and review your route and policy configuration. To learn more about policies, see the About policies docs.

  6. Connect to the MCP test server with the agentgateway UI playground.

    1. Go to the agentgateway UI Playground.

    2. In the Testing card, review your Connection details and click Connect. The agentgateway UI connects to the target that you configured and retrieves the tools that are exposed on the target.

    3. Verify that you see a list of Available Tools.

  7. Verify access to a tool.

    1. From the Available Tools list, select the echo tool.

    2. In the message field, enter any string, such as This is my first agentgateway setup., and click Run Tool.

    3. Verify that you see your message echoed in the Response card.

Next

With your agentgateway up and running, you can now explore the following tasks:

About