MCP Server Integration

Model Context Protocol (MCP) servers enable you to extend the Gemini CLI with custom tools, resources, and data sources. MCP servers act as a bridge between the Gemini model and external systems.

What is an MCP Server?

An MCP server is an application that exposes capabilities to the Gemini CLI through the Model Context Protocol. It enables the CLI to:

Discover Tools

List available tools with descriptions and parameters through standardized schemas

Execute Tools

Call specific tools with arguments and receive structured responses

Access Resources

Read data from exposed resources (files, API payloads, reports)

With MCP servers, you can perform actions beyond built-in features like:

Interacting with databases
Calling external APIs
Running custom scripts
Implementing specialized workflows

Architecture

The Gemini CLI integrates with MCP servers through a sophisticated discovery and execution system.

Discovery Layer

The discovery process:

Iterates through configured servers from settings.json
Establishes connections using appropriate transport mechanisms
Fetches tool definitions from each server
Sanitizes and validates tool schemas for Gemini API compatibility
Registers tools with conflict resolution
Fetches and registers resources if exposed

Execution Layer

Each discovered MCP tool:

Handles confirmation logic based on trust settings
Manages tool execution with proper parameters
Processes responses for both LLM context and user display
Maintains connection state and handles timeouts

Transport Mechanisms

Stdio
SSE
HTTP

Spawns a subprocess and communicates via stdin/stdout. Best for local servers.

{
  "command": "node",
  "args": ["server.js"]
}

Connects to Server-Sent Events endpoints. Best for remote servers.

{
  "url": "https://api.example.com/sse"
}

Uses HTTP streaming for communication. Best for HTTP-based services.

{
  "httpUrl": "https://api.example.com/mcp"
}

Configuration

Configure MCP servers in your settings.json file using the mcpServers object.

Basic Structure

{
  "mcpServers": {
    "serverName": {
      "command": "path/to/server",
      "args": ["--arg1", "value1"],
      "env": {
        "API_KEY": "$MY_API_TOKEN"
      },
      "cwd": "./server-directory",
      "timeout": 30000,
      "trust": false
    }
  }
}

Configuration Properties

Required (one of the following)

command

string

Path to the executable for Stdio transport

url

string

SSE endpoint URL (e.g., "http://localhost:8080/sse")

httpUrl

string

HTTP streaming endpoint URL

Optional

args

string[]

Command-line arguments for Stdio transport

headers

object

Custom HTTP headers for url or httpUrl transports

env

object

Environment variables for the server process. Supports $VAR_NAME or ${VAR_NAME} syntax (all platforms), or %VAR_NAME% (Windows only)

cwd

string

Working directory for Stdio transport

timeout

number

default:"600000"

Request timeout in milliseconds (default: 10 minutes)

trust

boolean

default:"false"

When true, bypasses all tool call confirmations for this server

includeTools

string[]

Allowlist of tool names to include from this server

excludeTools

string[]

Blocklist of tool names to exclude from this server (takes precedence over includeTools)

Environment Variable Expansion

Securely reference environment variables without hardcoding sensitive information:

{
  "env": {
    "API_KEY": "$MY_EXTERNAL_TOKEN",
    "LOG_LEVEL": "${LOG_LEVEL}",
    "TEMP_DIR": "%TEMP%"
  }
}

Supported syntaxes:

POSIX/Bash: $VARIABLE_NAME or ${VARIABLE_NAME} (all platforms)
Windows: %VARIABLE_NAME% (Windows only)

Undefined variables resolve to empty strings.

Example Configurations

Python MCP Server (Stdio)

{
  "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
    }
  }
}

Node.js MCP Server (Stdio)

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

Docker-based MCP Server

{
  "mcpServers": {
    "dockerizedServer": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "API_KEY",
        "-v",
        "${PWD}:/workspace",
        "my-mcp-server:latest"
      ],
      "env": {
        "API_KEY": "$EXTERNAL_SERVICE_TOKEN"
      }
    }
  }
}

HTTP MCP Server with Headers

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

Server with Tool Filtering

{
  "mcpServers": {
    "filteredServer": {
      "command": "python",
      "args": ["-m", "my_mcp_server"],
      "includeTools": ["safe_tool", "file_reader", "data_processor"],
      "excludeTools": ["dangerous_tool", "file_deleter"],
      "timeout": 30000
    }
  }
}

OAuth Authentication

The Gemini CLI supports OAuth 2.0 authentication for remote MCP servers.

Automatic OAuth Discovery

{
  "mcpServers": {
    "discoveredServer": {
      "url": "https://api.example.com/sse"
    }
  }
}

The CLI automatically:

Detects when OAuth is required (401 responses)
Discovers OAuth endpoints from server metadata
Performs dynamic client registration if supported
Handles the OAuth flow and token management

Authentication Flow

Initial Connection

Connection attempt fails with 401 Unauthorized

OAuth Discovery

Finds authorization and token endpoints

Browser Authentication

Opens browser for user authentication

Token Exchange

Exchanges authorization code for access tokens

Token Storage

Stores tokens securely for future use

Connection Retry

Retries connection with valid tokens

OAuth authentication requires:

Local browser access
Ability to receive redirects on http://localhost:7777/oauth/callback

This won’t work in headless environments or remote SSH sessions without X11 forwarding.

Managing OAuth

Use the /mcp auth command:

# List servers requiring authentication
/mcp auth

# Authenticate with a specific server
/mcp auth serverName

# Re-authenticate if tokens expire
/mcp auth serverName

MCP Resources

Some MCP servers expose contextual resources that can be referenced in conversations.

Referencing Resources

Use the @ syntax to reference resources:

@server://resource/path

Resource URIs appear in the completion menu alongside filesystem paths. When you submit, the CLI calls resources/read and injects the content.

Viewing Resources

The /mcp command displays available resources:

/mcp

Shows a Resources section for each connected server.

MCP Prompts as Slash Commands

MCP servers can expose predefined prompts as slash commands.

Example Server

import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
import { z } from 'zod';

const server = new McpServer({
  name: 'prompt-server',
  version: '1.0.0',
});

server.registerPrompt(
  'poem-writer',
  {
    title: 'Poem Writer',
    description: 'Write a nice haiku',
    argsSchema: { title: z.string(), mood: z.string().optional() },
  },
  ({ title, mood }) => ({
    messages: [
      {
        role: 'user',
        content: {
          type: 'text',
          text: `Write a haiku${mood ? ` with the mood ${mood}` : ''} called ${title}`,
        },
      },
    ],
  }),
);

const transport = new StdioServerTransport();
await server.connect(transport);

Invoking Prompts

# Named arguments
/poem-writer --title="Gemini CLI" --mood="reverent"

# Positional arguments
/poem-writer "Gemini CLI" reverent

Managing MCP Servers

Use the gemini mcp command group to manage server configurations.

Add a Server

# Stdio server
gemini mcp add my-server python server.py --arg value

# HTTP server
gemini mcp add --transport http http-server https://api.example.com/mcp/

# SSE server with auth
gemini mcp add --transport sse --header "Authorization: Bearer token" sse-server https://api.example.com/sse/

List Servers

gemini mcp list

Example output:

✓ stdio-server: command: python3 server.py (stdio) - Connected
✓ http-server: https://api.example.com/mcp (http) - Connected
✗ sse-server: https://api.example.com/sse (sse) - Disconnected

Remove a Server

gemini mcp remove my-server

Enable/Disable Servers

# Disable a server
gemini mcp disable my-server

# Enable a server
gemini mcp enable my-server

# Session-only change
gemini mcp disable my-server --session

Returning Rich Content

MCP tools can return multi-part content including text, images, and audio.

Example Response

{
  "content": [
    {
      "type": "text",
      "text": "Here is the logo you requested."
    },
    {
      "type": "image",
      "data": "BASE64_ENCODED_IMAGE_DATA_HERE",
      "mimeType": "image/png"
    },
    {
      "type": "text",
      "text": "The logo was created in 2025."
    }
  ]
}

Supported content types:

text
image
audio
resource (embedded content)
resource_link

Security

Environment Sanitization

By default, the CLI redacts sensitive environment variables to prevent unintended exposure:

Core project keys: GEMINI_API_KEY, GOOGLE_API_KEY
Patterns: *TOKEN*, *SECRET*, *PASSWORD*, *KEY*, *AUTH*, *CREDENTIAL*
Certificates and private key patterns

Explicit Overrides: To pass an environment variable to an MCP server, explicitly define it in the env property:

{
  "env": {
    "MY_KEY": "$MY_KEY"
  }
}

Use environment variable expansion instead of hardcoding secrets.

Trust Settings

The trust option bypasses all confirmation dialogs. Use cautiously and only for servers you completely control.

Troubleshooting

Server Won’t Connect

Verify command, args, and cwd are correct
Test the server command manually
Check that all dependencies are installed
Review CLI output for error messages
Verify execution permissions

No Tools Discovered

Ensure your server registers tools correctly
Verify MCP protocol implementation
Review server logs (stderr output)
Manually test tool discovery endpoint

Tools Not Executing

Validate parameter schemas
Verify input schemas are valid JSON Schema
Check for unhandled exceptions
Consider increasing the timeout setting

Debug Mode

Run with --debug flag or press F12 in interactive mode:

gemini --debug

Get Started

Core Concepts

CLI Usage

Tools & Extensions

Advanced

Resources

​What is an MCP Server?

Discover Tools

Execute Tools

Access Resources

​Architecture

​Discovery Layer

​Execution Layer

​Transport Mechanisms

​Configuration

​Basic Structure

​Configuration Properties

​Required (one of the following)

​Optional

​Environment Variable Expansion

​Example Configurations

​Python MCP Server (Stdio)

​Node.js MCP Server (Stdio)

​Docker-based MCP Server

​HTTP MCP Server with Headers

​Server with Tool Filtering

​OAuth Authentication

​Automatic OAuth Discovery

​Authentication Flow

​Managing OAuth

​MCP Resources

​Referencing Resources

​Viewing Resources

​MCP Prompts as Slash Commands

​Example Server

​Invoking Prompts

​Managing MCP Servers

​Add a Server

​List Servers

​Remove a Server

​Enable/Disable Servers

​Returning Rich Content

​Example Response

​Security

​Environment Sanitization

​Trust Settings

​Troubleshooting

​Server Won’t Connect

​No Tools Discovered

​Tools Not Executing

​Debug Mode

​Next Steps

Build an Extension

MCP Specification

Build docs developers (and LLMs) love

What is an MCP Server?

Architecture

Discovery Layer

Execution Layer

Transport Mechanisms

Configuration

Basic Structure

Configuration Properties

Required (one of the following)

Optional

Environment Variable Expansion

Example Configurations

Python MCP Server (Stdio)

Node.js MCP Server (Stdio)

Docker-based MCP Server

HTTP MCP Server with Headers

Server with Tool Filtering

OAuth Authentication

Automatic OAuth Discovery

Authentication Flow

Managing OAuth

MCP Resources

Referencing Resources

Viewing Resources

MCP Prompts as Slash Commands

Example Server

Invoking Prompts

Managing MCP Servers

Add a Server

List Servers

Remove a Server

Enable/Disable Servers

Returning Rich Content

Example Response

Security

Environment Sanitization

Trust Settings

Troubleshooting

Server Won’t Connect

No Tools Discovered

Tools Not Executing

Debug Mode

Next Steps