MCP Architecture & Setup

MCP (Model Context Protocol) servers are the integration layer that gives Gemini CLI access to external systems. An MCP server is a process that exposes tools, resources, and prompts over a standardized JSON-RPC protocol. Gemini CLI starts the server process, discovers its capabilities, and makes those capabilities available alongside built-in tools. The key insight: MCP servers are not plugins or extensions — they are standalone processes that communicate over stdin/stdout or HTTP. This architecture means any language, any runtime, any system can be an MCP server.

Configuration lives in .gemini/settings.json under the mcpServers key. Each server entry specifies a command to launch the process, arguments, optional environment variables, and optional tool filtering. The server starts when Gemini CLI launches and stays running for the session. Multiple servers can run simultaneously — a database server, a GitHub server, and a custom internal server all providing tools in the same session.

{
  "mcpServers": {
    "postgres": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres"],
      "env": {
        "DATABASE_URL": "postgresql://localhost:5432/mydb"
      }
    },
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_TOKEN": "${GITHUB_TOKEN}"
      },
      "includeTools": ["create_pull_request", "list_issues", "get_file_contents"]
    },
    "memory": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-memory"]
    }
  }
}

1. Choose your server Browse the MCP server registry or the awesome-mcp-servers list on GitHub. Identify the server that matches your integration need — database, API, cloud service, or custom tool.
2. Add the configuration Add an entry to mcpServers in .gemini/settings.json. Specify command, args, env, and any tool filtering (includeTools/excludeTools).
3. Verify the connection Launch Gemini CLI and run /tools to confirm the server's tools appear. If tools are missing, check server logs and environment variables.
4. Filter aggressively Use includeTools to whitelist only the tools you need. Every tool description consumes context tokens. A GitHub server with 30 tools wastes context when you only need 4.