Gateway MCP Servers

Declare downstream MCP servers once; every gateway agent that lists the name gets a shared, pooled client

Next

Declare downstream MCP servers once at the gateway and every agent that lists the server name gets the same pooled, shared client — not N connections per server.

Quick Start

1. One stdio server, two agents

   # gateway.yaml
   mcp_servers:
     github:
       command: npx
       args: ["-y", "@modelcontextprotocol/server-github"]
   
   agents:
     support:
       instructions: "Help users file GitHub issues."
       model: gpt-4o-mini
       tools: [github]
     triage:
       instructions: "Label and route incoming issues."
       model: gpt-4o-mini
       tools: [github]

   One npx process serves both agents.

2. Mix stdio and HTTP servers

   mcp_servers:
     github:
       command: npx
       args: ["-y", "@modelcontextprotocol/server-github"]
     search:
       url: https://mcp.example.com/sse
       headers:
         Authorization: Bearer ${SEARCH_MCP_TOKEN}
   
   agents:
     support:
       instructions: "Answer questions using GitHub and web search."
       tools: [github, search]

3. String shorthand for a local binary

   mcp_servers:
     files: /usr/local/bin/filesystem-mcp
   
   agents:
     librarian:
       instructions: "Find and summarise local documents."
       tools: [files]

Start the gateway with your config:

praisonai gateway start --config gateway.yaml

How It Works

Every agent that lists the server name walks the same path and lands on the same client.

Configuration

Each key under mcp_servers: is the server’s name (also its tool-name prefix), and the value is its spec.

Referencing a server from an agent

List the server name in an agent’s tools: to attach the pooled client.

agents:
  support:
    tools: [github, internet_search]   # MCP server + built-in tool

Names that are not in mcp_servers: fall through to the normal tool resolver, so built-in tools work alongside MCP servers.

Tool-name namespacing

Tools from a server named github are exposed as github_<tool>, so two servers that each offer a search tool never shadow each other.

Hot Reload

The pool keys each client by name and spec, so a reload only reconnects what changed.

Failure Modes

• Bad spec (no command and no url) — logged, skipped, gateway continues.
• Server fails to start — logged, skipped, gateway continues; the agent still registers without that server’s tools.
• stdio server dies mid-session — the core praisonaiagents.MCP client restarts it on the next call.
• Gateway stops — every pooled client is shut down.

Security

MCP tools from mcp_servers: run through the agent’s normal tool path, so existing tool policy and approval checks still apply.

Configuration Options

Best Practices

Related