subagentic.ai RSS X YouTube GitHub
AI-generated illustration

How-Tos

How to add an MCP server with Gemini CLI

Register stdio and HTTP MCP servers in Gemini CLI through settings.json, including headers and environment variables.

gemini-climcp

Gemini CLI connects to MCP servers you list under mcpServers in settings.json. Until a server is named there and given a transport, discovery has nothing to open. The Gemini CLI guide for MCP servers documents that registration as configuration: stdio for a local process, SSE or streamable HTTP for a remote endpoint, plus environment variables and headers when you need them.

What you are adding

An MCP server is an application that exposes tools and resources through the Model Context Protocol. The guide describes it as a bridge between the model and your local environment or another service, such as an API. Once connected, Gemini CLI can list tools and their parameters, call a tool with arguments, and read resources the server exposes.

When Gemini CLI starts, discoverMcpTools() walks mcpServers, establishes a connection, fetches tool definitions, sanitizes schemas, and registers the tools. Each tool gets a fully qualified name in the form mcp_{serverName}_{toolName}.

Do not put underscores in the server name. The policy parser splits that qualified name on the first underscore after the mcp_ prefix. The guide's warning uses my-server rather than my_server, because an underscore can make wildcard rules fail silently.

Pick a transport

The guide supports three transports. Which one you get depends on the required property you set:

  • Stdio uses command, the path to an executable. The CLI spawns a subprocess and communicates over stdin and stdout. args and cwd apply to this transport.
  • SSE uses url, the Server-Sent Events endpoint.
  • Streamable HTTP uses httpUrl, the HTTP streaming endpoint.

One of command, url, or httpUrl is required. Optional headers apply when the entry uses url or httpUrl. Optional env supplies environment variables for the server process.

A top-level mcp object can limit which configured names actually connect:

{
  "mcp": {
    "allowed": ["my-trusted-server"],
    "excluded": ["experimental-server"]
  }
}

If mcp.allowed is set, only names from that list (matching keys in mcpServers) are connected. Names in mcp.excluded are not connected. The same object documents mcp.serverCommand as a global command to start an MCP server. The fetched guide names that key and does not show an example value.

Register a stdio server

A Python server from the guide, including arguments, a working directory, expanded environment variables, and a timeout:

{
  "mcpServers": {
    "pythonTools": {
      "command": "python",
      "args": ["-m", "my_mcp_server", "--port", "8080"],
      "cwd": "./mcp-servers/python",
      "env": {
        "DATABASE_URL": "$DB_CONNECTION_STRING",
        "API_KEY": "${EXTERNAL_API_KEY}"
      },
      "timeout": 15000
    }
  }
}

timeout is milliseconds. If you omit it, the documented default is 600,000 milliseconds, or 10 minutes. trust defaults to false, so tool calls still ask for confirmation. The Node example on the same page sets trust to true, which bypasses those confirmations for that server:

{
  "mcpServers": {
    "nodeServer": {
      "command": "node",
      "args": ["dist/server.js", "--verbose"],
      "cwd": "./mcp-servers/node",
      "trust": true
    }
  }
}

Values in env expand $VAR_NAME or ${VAR_NAME} on every platform, and %VAR_NAME% on Windows only. A variable that is not defined in the current environment becomes an empty string.

Before it spawns a server, Gemini CLI redacts sensitive variables inherited from the host process. The guide includes core keys such as GEMINI_API_KEY and GOOGLE_API_KEY, names matching *TOKEN*, *SECRET*, *PASSWORD*, *KEY*, *AUTH*, or *CREDENTIAL*, and certificate or private-key patterns. If a server must receive one of those, write it explicitly in that server's env block. Explicit entries are not redacted. Do not hardcode the secret; expand it from the host environment. The guide's stdio example does that for a GitHub token:

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@github/github-mcp-server"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "$GITHUB_PERSONAL_ACCESS_TOKEN"
      }
    }
  }
}

That explicit env block can live in settings.json, or in mcp_config.json when you are configuring standard MCP clients or remote skills. The page does not say which file to prefer.

Register an HTTP server and headers

Streamable HTTP uses httpUrl and does not set command. This is the documented HTTP example:

{
  "mcpServers": {
    "httpServer": {
      "httpUrl": "http://localhost:3000/mcp",
      "timeout": 5000
    }
  }
}

Custom headers are an object on the same entry. The guide's HTTP server with a bearer token and extra headers is:

{
  "mcpServers": {
    "httpServerWithAuth": {
      "httpUrl": "http://localhost:3000/mcp",
      "headers": {
        "Authorization": "Bearer your-api-token",
        "X-Custom-Header": "custom-value",
        "Content-Type": "application/json"
      },
      "timeout": 5000
    }
  }
}

For SSE, set url instead of httpUrl. The same headers object applies to either property. A static authorization header is not the OAuth flow later in the guide. If a remote server returns 401 and supports discovery, the CLI can find OAuth endpoints, open a browser, and store tokens in ~/.gemini/mcp-oauth-tokens.json. That path needs a local browser and a redirect written in the guide as http://localhost:<random-port>/oauth/callback. The page says it will not work in a headless environment, over SSH without X11 forwarding, or in a container without a browser.

Inside the session, the documented authentication commands are:

# List servers requiring authentication
/mcp auth

# Authenticate with a specific server
/mcp auth serverName

# Re-authenticate if tokens expire
/mcp auth serverName

Limit tools, then check status

includeTools is an allowlist: only those tool names from this server are available. excludeTools removes names even if they also appear in the allowlist. If you set neither, every tool the server exposes is enabled.

If an extension already provides the server, a local mcpServers entry merges with the extension defaults. Exclusions are combined. If both sides provide an allowlist, only tools present in both lists stay enabled. Your local env value wins when the same variable is set in both places. Scalar properties such as command, url, and timeout are replaced by your local values when you set them.

After you start Gemini CLI, the status command in the guide is:

/mcp

It lists each configured server, a status of CONNECTED, CONNECTING, or DISCONNECTED, a configuration summary that excludes sensitive data, and the tools discovered from that server. A finished pass reports discovery state COMPLETED. A server that provides no usable tools has its connection closed after discovery.

If the status stays DISCONNECTED, the guide's checks are to verify command, args, and cwd, run the server command yourself, confirm dependencies are installed, read the CLI error output, and confirm the CLI can execute the command. If the server connects but lists no tools, confirm it registers tools and implements MCP tool listing.

Unless trust is true, or you have already allowed the server or the tool, a call still asks you to proceed once, always allow this tool, always allow this server, or cancel.

The fetched guide does not say whether a given settings.json is a user file or a project file.

Copy one complete example from the guide — stdio with command and env, or HTTP with httpUrl and headers — into mcpServers, start Gemini CLI, and run /mcp. A CONNECTED line and a tool list are the check that registration worked. Read the OAuth section of the same guide before you point the CLI at a remote server that will not accept a static header.

Sources