tessl/npm-google--gemini-cli

Open-source AI agent providing terminal access to Gemini models with extensible tool support and developer-focused features

Overview

Eval results

Files

MCP Integration

Name: tessl/npm-google--gemini-cli
Author: tessl

The Gemini CLI integrates with the Model Context Protocol (MCP) to connect external tools and services, providing support for multiple transport types and comprehensive server management capabilities.

Capabilities

MCP Server Configuration

MCP servers can be configured with different transport mechanisms and connection options.

interface MCPServerConfig {
  // Stdio transport configuration
  command?: string;
  args?: string[];
  env?: Record<string, string>;

  // Server-Sent Events transport
  url?: string;

  // HTTP transport
  httpUrl?: string;

  // Common HTTP configuration (for SSE and HTTP)
  headers?: Record<string, string>;

  // Connection and behavior settings
  timeout?: number;
  trust?: boolean;
  description?: string;
  includeTools?: string[];
  excludeTools?: string[];

  // Extension association
  extensionName?: string;
}

Transport Types

MCP supports multiple transport mechanisms for server communication.

Stdio Transport

Standard input/output communication for local processes.

interface StdioTransport {
  /** Command to execute */
  command: string;

  /** Command arguments */
  args?: string[];

  /** Environment variables */
  env?: Record<string, string>;
}

Usage Examples:

{
  "calculator": {
    "command": "python",
    "args": ["/path/to/calculator-server.py"],
    "env": {
      "CALC_PRECISION": "10"
    },
    "description": "Mathematical calculation server"
  }
}

Server-Sent Events (SSE) Transport

HTTP-based streaming communication using Server-Sent Events.

interface SSETransport {
  /** SSE endpoint URL */
  url: string;

  /** HTTP headers */
  headers?: Record<string, string>;

  /** Connection timeout in milliseconds */
  timeout?: number;
}

Usage Examples:

{
  "weather-service": {
    "url": "http://localhost:3000/mcp/sse",
    "headers": {
      "Authorization": "Bearer your-api-token",
      "Content-Type": "application/json"
    },
    "timeout": 10000
  }
}

HTTP Transport

Direct HTTP request/response communication.

interface HTTPTransport {
  /** HTTP endpoint URL */
  httpUrl: string;

  /** HTTP headers */
  headers?: Record<string, string>;

  /** Request timeout in milliseconds */
  timeout?: number;
}

Usage Examples:

{
  "api-gateway": {
    "httpUrl": "https://api.example.com/mcp",
    "headers": {
      "Authorization": "Bearer api-key-123",
      "X-API-Version": "1.0"
    },
    "timeout": 5000
  }
}

MCP Management API

Server Configuration Loading

/**
 * Load MCP server configurations from settings and extensions
 * @param settings - Current application settings
 * @param extensions - Active extensions
 * @returns Merged MCP server configurations
 */
function loadMcpServerConfigs(
  settings: Settings,
  extensions: Extension[]
): Record<string, MCPServerConfig>;

/**
 * Validate MCP server configuration
 * @param config - Server configuration to validate
 * @returns Validation result
 */
function validateMcpServerConfig(
  config: MCPServerConfig
): {
  valid: boolean;
  errors: string[];
  warnings: string[];
};

Server Lifecycle Management

interface MCPServer {
  /** Server name */
  name: string;

  /** Server configuration */
  config: MCPServerConfig;

  /** Connection status */
  status: 'disconnected' | 'connecting' | 'connected' | 'error';

  /** Available tools */
  tools: MCPTool[];

  /** Connection error if any */
  error?: string;
}

/**
 * Start MCP server connection
 * @param name - Server name
 * @param config - Server configuration
 * @returns Promise resolving to server instance
 */
function startMcpServer(
  name: string,
  config: MCPServerConfig
): Promise<MCPServer>;

/**
 * Stop MCP server connection
 * @param name - Server name
 */
function stopMcpServer(name: string): Promise<void>;

/**
 * Get status of all MCP servers
 * @returns Current server status information
 */
function getMcpServerStatus(): Record<string, MCPServer>;

Tool Discovery and Filtering

interface MCPTool {
  /** Tool name */
  name: string;

  /** Tool description */
  description?: string;

  /** Tool parameters schema */
  inputSchema: any;

  /** Server providing this tool */
  serverName: string;
}

/**
 * Discover available tools from all connected MCP servers
 * @returns Array of available tools
 */
function discoverMcpTools(): Promise<MCPTool[]>;

/**
 * Filter tools based on server configuration
 * @param tools - Available tools
 * @param config - Server configuration with include/exclude lists
 * @returns Filtered tools array
 */
function filterMcpTools(
  tools: MCPTool[],
  config: MCPServerConfig
): MCPTool[];

CLI Commands

Adding MCP Servers

gemini mcp add <name> <commandOrUrl> [args...] [options]

Add Command Options

--scope, -s <scope>           # Configuration scope: user, project
--transport, -t <type>        # Transport type: stdio, sse, http
--env, -e <KEY=value>         # Environment variables (repeatable)
--header, -H <header>         # HTTP headers for SSE/HTTP (repeatable)
--timeout <ms>                # Connection timeout in milliseconds
--trust                       # Trust server (bypass confirmations)
--description <desc>          # Server description
--include-tools <tools>       # Include specific tools (comma-separated)
--exclude-tools <tools>       # Exclude specific tools (comma-separated)

Usage Examples:

# Add stdio server
gemini mcp add calculator python /path/to/calc-server.py

# Add HTTP server with authentication
gemini mcp add weather-api http://api.weather.com/mcp \
  --transport http \
  --header "Authorization: Bearer token123" \
  --timeout 10000 \
  --trust

# Add server with environment variables
gemini mcp add database-tool python db-server.py \
  --env "DB_HOST=localhost" \
  --env "DB_PORT=5432" \
  --scope user

# Add server with tool filtering
gemini mcp add file-processor ./processor-server \
  --include-tools "process_file,validate_file" \
  --exclude-tools "delete_file"

Managing MCP Servers

gemini mcp list               # List configured MCP servers
gemini mcp remove <name>      # Remove MCP server by name

Server Status and Debugging

gemini mcp status             # Show server connection status
gemini mcp test <name>        # Test server connection
gemini mcp logs <name>        # Show server logs (if available)

Configuration Integration

Settings Configuration

MCP servers can be configured in the settings system:

interface MCPSettings {
  /** Default server command template */
  serverCommand?: string;

  /** Globally allowed server names */
  allowed?: string[];

  /** Globally excluded server names */
  excluded?: string[];
}

Usage Examples:

{
  "mcp": {
    "allowed": ["calculator", "weather-api"],
    "excluded": ["untrusted-server"]
  },
  "mcpServers": {
    "calculator": {
      "command": "python",
      "args": ["~/tools/calculator-server.py"],
      "trust": true,
      "description": "Mathematical calculations"
    },
    "weather-api": {
      "url": "http://localhost:3000/weather-mcp",
      "timeout": 5000,
      "headers": {
        "API-Key": "your-key-here"
      }
    }
  }
}

Extension Integration

Extensions can provide MCP servers automatically:

// In gemini-extension.json
{
  "name": "my-extension",
  "version": "1.0.0",
  "mcpServers": {
    "extension-tool": {
      "command": "node",
      "args": ["{{extensionPath}}/server.js"],
      "description": "Extension-provided tools"
    }
  }
}

Security and Trust

Server Trust Model

interface TrustLevel {
  /** Allow server without confirmation prompts */
  trusted: boolean;

  /** Allow tool execution without individual approval */
  autoApprove: boolean;

  /** Trust level reason/source */
  reason: 'user' | 'extension' | 'system';
}

/**
 * Check if server is trusted
 * @param serverName - Name of server to check
 * @param config - Server configuration
 * @returns Trust level information
 */
function checkServerTrust(
  serverName: string,
  config: MCPServerConfig
): TrustLevel;

Security Considerations

interface SecurityPolicy {
  /** Require confirmation for new servers */
  requireConfirmationForNewServers: boolean;

  /** Maximum allowed timeout */
  maxTimeout: number;

  /** Allowed transport types */
  allowedTransports: ('stdio' | 'sse' | 'http')[];

  /** Network access restrictions */
  networkRestrictions: {
    allowLocalhost: boolean;
    allowPrivateNetworks: boolean;
    blockedDomains: string[];
  };
}

Error Handling

Connection Errors

interface MCPConnectionError {
  /** Server name */
  server: string;

  /** Error type */
  type: 'timeout' | 'auth' | 'network' | 'protocol';

  /** Error message */
  message: string;

  /** Retry suggestions */
  suggestions: string[];

  /** Whether error is recoverable */
  recoverable: boolean;
}

/**
 * Handle MCP server connection errors
 * @param error - Connection error details
 * @returns Recovery action or null
 */
function handleMcpError(
  error: MCPConnectionError
): Promise<'retry' | 'ignore' | 'remove' | null>;

Tool Execution Errors

interface MCPToolError {
  /** Tool name */
  tool: string;

  /** Server name */
  server: string;

  /** Error type */
  type: 'validation' | 'execution' | 'timeout';

  /** Error details */
  message: string;

  /** Input that caused error */
  input?: any;
}

Advanced Features

Server Health Monitoring

interface ServerHealthCheck {
  /** Server name */
  name: string;

  /** Health status */
  status: 'healthy' | 'degraded' | 'unhealthy';

  /** Response time in milliseconds */
  responseTime: number;

  /** Last check timestamp */
  lastCheck: Date;

  /** Health metrics */
  metrics: {
    successRate: number;
    averageResponseTime: number;
    errorCount: number;
  };
}

/**
 * Perform health check on MCP server
 * @param serverName - Server to check
 * @returns Health status
 */
function checkServerHealth(
  serverName: string
): Promise<ServerHealthCheck>;

Dynamic Server Discovery

/**
 * Discover MCP servers on the network
 * @param options - Discovery options
 * @returns Discovered server configurations
 */
function discoverMcpServers(options: {
  timeout?: number;
  protocols?: ('http' | 'sse')[];
  portRange?: [number, number];
}): Promise<MCPServerConfig[]>;

Server Capabilities

interface ServerCapabilities {
  /** Supported tools */
  tools: string[];

  /** Supported transport types */
  transports: string[];

  /** Protocol version */
  protocolVersion: string;

  /** Server metadata */
  metadata: {
    name: string;
    version: string;
    description?: string;
  };
}

/**
 * Query server capabilities
 * @param serverName - Server to query
 * @returns Server capabilities
 */
function getServerCapabilities(
  serverName: string
): Promise<ServerCapabilities>;

Install with Tessl CLI

npx tessl i tessl/npm-google--gemini-cli

docs

interactive-commands.md

mcp-integration.md

themes.md

tile.json

tessl/npm-google--gemini-cli

mcp-integration.md.css-3qkkll{font-size:var(--chakra-font-sizes-sm);font-weight:var(--chakra-font-weights-normal);color:var(--chakra-colors-gray-300);}docs/

MCP Integration

Capabilities

MCP Server Configuration

Transport Types

Stdio Transport

Server-Sent Events (SSE) Transport

HTTP Transport

MCP Management API

Server Configuration Loading

Server Lifecycle Management

Tool Discovery and Filtering

CLI Commands

Adding MCP Servers

Add Command Options

Managing MCP Servers

Server Status and Debugging

Configuration Integration

Settings Configuration

Extension Integration

Security and Trust

Server Trust Model

Security Considerations

Error Handling

Connection Errors

Tool Execution Errors

Advanced Features

Server Health Monitoring

Dynamic Server Discovery

Server Capabilities

mcp-integration.mddocs/