Multi-Server Orchestration

Running multiple MCP servers simultaneously is where Gemini CLI's integration model shines — and where it gets complex. Each server is an independent process with its own lifecycle, memory footprint, and failure mode. A typical production setup might run 4-6 servers: GitHub for version control, a database server, a custom API server, memory for session persistence, and a fetch server for HTTP requests. All tools from all servers appear in a unified tool list.

Tool name collisions are the first problem at scale. Two servers can expose tools with the same name. Gemini CLI handles this by prefixing tools with the server name when ambiguous, but the behavior is not always predictable. The defensive approach: use includeTools on every server to expose only the tools you need, and ensure no two servers expose identically-named tools. The excludeTools alternative removes specific tools while keeping the rest — useful when a server has 20 good tools and 2 problematic ones.

Resource consumption scales linearly with server count. Each MCP server is a separate Node.js (or Python, or Go) process. Five servers means five processes consuming memory, five sets of tool descriptions consuming context tokens, and five potential points of failure. The expert approach: audit your server list quarterly. Remove servers you are not actively using. Combine related functionality into a single custom server rather than running three single-purpose servers.

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": { "GITHUB_TOKEN": "${GITHUB_TOKEN}" },
      "includeTools": ["create_pull_request", "list_issues", "get_file_contents"]
    },
    "postgres": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres"],
      "env": { "DATABASE_URL": "${DATABASE_URL}" }
    },
    "fetch": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-fetch"],
      "excludeTools": ["fetch_html"]
    },
    "memory": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-memory"],
      "timeout": 5000
    },
    "internal": {
      "command": "node",
      "args": ["./tools/mcp-server/index.js"],
      "env": { "API_KEY": "${INTERNAL_API_KEY}" },
      "timeout": 10000
    }
  }
}