MCP Federation

Expose a single MCP endpoint that aggregates tools from multiple backend servers with unified security.

What you’ll build

In this tutorial, you configure the following.

1. Configure agentgateway to federate multiple MCP servers
2. Combine filesystem and memory servers into a single endpoint
3. Access tools from both servers with automatic name prefixing
4. Test federated tools in the Playground

Before you begin

• Node.js installed

Step 1: Install agentgateway

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

Step 2: Create the config

cat > config.yaml << 'EOF'
# 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: filesystem
            stdio:
              cmd: npx
              args: ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"]
          - name: memory
            stdio:
              cmd: npx
              args: ["-y", "@modelcontextprotocol/server-memory"]
EOF

Step 3: Start agentgateway

agentgateway -f config.yaml

Example output:

INFO agentgateway: Listening on 0.0.0.0:3000
INFO agentgateway: Admin UI available at http://localhost:15000/ui/

Step 4: View backends in the UI

Go to http://localhost:15000/ui/ and click Backends to see your federated MCP servers:

The UI shows:

• 1 total backend with 1 MCP configuration
• MCP: filesystem, memory - Both servers combined into one backend
• 2 targets - The filesystem and memory MCP servers

Step 5: Test in the Playground

Click Playground to test your federated tools:

1. Select Route 1 in the Routes panel
2. Click Connect to discover all tools
3. Available Tools shows tools from both servers:
   • filesystem_read_file - Read the complete contents of a file
   • filesystem_read_text_file - Read file contents as text
   • filesystem_write_file - Create or overwrite a file
   • filesystem_list_directory - List directory contents
   • And more…

Notice tools are prefixed with their server name (filesystem_ and memory_).

Step 6: Run a tool

1. Click on filesystem_read_text_file in the Available Tools list
2. Enter a path (e.g., /tmp/test.txt)
3. Click Run Tool

You’ll see the file contents in the response panel.

Adding more servers

Add GitHub tools (requires a token):

export GITHUB_TOKEN=your-github-token

targets:
- name: filesystem
  stdio:
    cmd: npx
    args: ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"]
- name: github
  stdio:
    cmd: npx
    args: ["-y", "@modelcontextprotocol/server-github"]
  env:
    GITHUB_PERSONAL_ACCESS_TOKEN: "${GITHUB_TOKEN}"

Next steps