Virtual MCP

Federate multiple MCP servers into a unified virtual MCP backend

Federate tools of multiple MCP servers on the agentgateway by using MCP multiplexingMultiplexA connection method for MCP servers that allows multiple MCP sessions to share a single transport connection, improving efficiency..

About multiplexing

Multiplexing combines multiple MCP servers (targets) within a single backend into one unified MCP server. All targets are exposed together so that clients can access tools from all targets simultaneously. Tools are prefixed with the target name (e.g., time_get_current_time, everything_echo)

Example multiplexing configuration

backends:
  - mcp:
      # Multiple targets for multiplexing
      targets:
        - name: time
          stdio:
            cmd: uvx
            args: ["mcp-server-time"]
        - name: everything
          stdio:
            cmd: npx
            args: ["@modelcontextprotocol/server-everything"]

Multiplexing vs. load balancing Although configured similarly, multiplexing is different than load balancing. Load balancing distributes requests across multiple backends. Each request goes to one backend, selected based on weight. You configure load balancing with multiple backends in a route (instead of multiple targets). For more information, see Backend routing.

Example load balancing configuration

routes:
  - backends:           # Multiple backends = load balancing
      - mcp:
          targets:
            - name: everything
              stdio:
                cmd: npx
                args: ["@modelcontextprotocol/server-everything"]
        weight: 1
      - mcp:
          targets:
            - name: everything
              stdio:
                cmd: npx
                args: ["@modelcontextprotocol/server-everything"]
        weight: 1

Before you begin

Configure the agentgateway

Download a multiplex configuration for your agentgateway.

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

Review the configuration file.

cat config.yaml

config.yaml

binds:
- port: 3000
  listeners:
  - routes:
    - backends:
      - mcp:
          targets:
          - name: time
            stdio:
              cmd: uvx
              args: ["mcp-server-time"]
          - name: everything
            stdio:
              cmd: npx
              args: ["@modelcontextprotocol/server-everything"]

Listener: An HTTP listener is configured and bound on port 3000. It includes a basic route that matches all traffic to an MCP backend.
Backend: The MCP backend defines two targets: time and everything. Note that the target names cannot include underscores (_). These targets are multiplexed together and exposed as a single unified MCP server to clients. All tools from both targets are available, prefixed with their target name.

Optional: To use the agentgateway UI playground later, add the following CORS policy to your config.yaml file. The config automatically reloads when you save the file.

# yaml-language-server: $schema=https://agentgateway.dev/schema/config
mcp:
  port: 3000
  policies:
    cors:
      allowOrigins:
        - "*"
      allowHeaders:
        - "*"
  targets:
...

Run the agentgateway.
```
agentgateway -f config.yaml
```

Verify access to tools

Open the agentgateway UI to view your listener and target configuration.
From the navigation menu under MCP, click Tool Playground.
If you see a banner prompting you to allow browser access, click Apply CORS. This adds the UI’s origin to the MCP CORS policy so the playground can open a session, and the configuration reloads automatically.
Click Initialize. The agentgateway UI opens an MCP session and lists the tools that are exposed across all targets in the backend.
Verify that the Result panel reports the discovered tools and that each tool name is prefixed with its target name, such as everything_echo and time_get_current_time. You now have a federated view of the tools from every target in the backend.
Verify access to a tool from the everything target.
1. From the Tool dropdown, select the everything_echo tool.
2. In the Message field, enter any string, such as hello world, and click Call tool.
3. Verify that the Result panel returns HTTP 200 and that your message is echoed in the Tool output.
Verify access to a tool from the time target.
1. From the Tool dropdown, select the time_get_current_time tool.
2. In the timezone field, enter a timezone, such as America/New_York, and click Call tool.
3. Verify that the Result panel returns HTTP 200 with the current time in the Tool output.