Gemini-mcp

Alph CLI Integration Notes • Detection is read-only: Alph only considers Gemini detected when an existing settings.json is present and readable. alph status will not create or initialize config files. • Initialization happens only during alph setup, which safely creates directories/files when needed.

Overview: Google’s Gemini CLI is an open-source AI agentic CLI that fully supports integrating external MCP servers[60]. It uses a ReAct loop with both built-in local tools and MCP servers to fulfill complex tasks[60]. For Alph CLI, Gemini CLI serves as a valuable reference for cross-platform MCP integration: it supports macOS, Linux, and Windows (including Cloud Shell) and provides tooling to manage MCP connections. Notably, Gemini CLI implements all three MCP transports – stdio, SSE, and HTTP – and offers a rich configuration system (settings.json) and command interface for discovering and controlling MCP servers[61][62]. Platform Compatibility & Installation • Installation of Gemini CLI: Gemini CLI is distributed as an open-source project (GitHub: google-gemini/gemini-cli) and can be installed via npm or binaries. On macOS/Linux, you can use npm (npm install -g @google-gemini/cli, hypothetically) or run it in Google Cloud Shell with no setup[63]. On Windows, it can be installed via npm under WSL or possibly as a standalone binary (the open-source repo indicates multi-platform support). Ensure Node.js environment is available if using the npm distribution, as Gemini CLI’s internal architecture is Node/TypeScript-based (it has packages like packages/core as mentioned in docs[64]). • Configuration Files: Gemini CLI uses a JSON config file named settings.json. There are two scopes: • User-level config: located in ~/.gemini/settings.json on macOS/Linux (and %UserProfile%.gemini\settings.json on Windows)[65][66]. Settings here apply globally to the user. • Project-level config: you can have a .gemini/settings.json in a project directory, which overrides/augments settings for that project context[67][68]. By default, gemini mcp add adds to the project config unless --scope user is specified[69][68]. Alph CLI should be prepared to handle both scopes. For instance, if integrating in a specific project directory, it may write to that project’s .gemini/settings.json for project-specific MCP servers, leaving global config untouched. This is useful for per-repo customization. • Initial State & Discovery: On first run, if no MCP servers are configured, running the command /mcp in Gemini CLI will open documentation in a browser by design[70]. This is a user-friendly hint (though possibly disruptive if done repeatedly – an early bug caused the docs tab to open each time /mcp was used with no servers[71]). Essentially, Gemini CLI does not auto-discover MCP servers on its own; they must be specified in settings.json or added via commands. Alph CLI can mirror this behavior by clearly requiring explicit configuration, avoiding “magic” discovery, to match user expectations from Gemini. • Adding MCP Servers (CLI vs Manual): Gemini CLI provides the gemini mcp command suite to manage servers without manually editing JSON: • gemini mcp add – adds a server[72]. • gemini mcp list – lists configured servers and their status[73][74]. • gemini mcp remove – removes a server from config[75]. Each of these accepts options like -s/--scope (user or project) and -t/--transport (specify stdio, sse, or http)[76]. For example, to add a local server globally: gemini mcp add -s user mytool /path/to/server --timeout 30000[77]. Or to add a remote HTTP server: gemini mcp add --transport http -s user search https://api.example.com/mcp --header "Authorization: Bearer XYZ"[78][79]. Under the hood, these commands update the corresponding settings.json. Alph CLI could either instruct users to use these commands for setup, or directly manipulate the JSON (ensuring the format is correct). Using Gemini’s own commands is safer to avoid schema mistakes. • Configuration Schema: In settings.json, MCP servers are defined under the "mcpServers" object[80]. Each server entry is keyed by a name and contains fields: • For stdio servers: "command" (executable path) – required, "args" – array of arguments, "cwd" – working directory (optional), "env" – environment variables (object), etc.[81][82]. • For remote SSE servers: "url" – the SSE endpoint URL[83]. • For remote HTTP servers: "httpUrl" – the HTTP endpoint URL for streamable HTTP[84]. Gemini CLI explicitly separates SSE vs HTTP by using different JSON keys (url vs httpUrl)[84]. For example: { "mcpServers": { "local-db": { "command": "/usr/local/bin/my_db_mcp", "args": ["--read-only"], "env": { "DB_TOKEN": "$DB_TOKEN" }, "timeout": 30000, "trust": false }, "linear": { "url": "https://mcp.linear.app/sse", "headers": { "Authorization": "Bearer " } }, "docs": { "httpUrl": "https://docs.example.com/mcp", "headers": { "X-API-Key": "" }, "timeout": 10000 } } } In this snippet: - local-db is a stdio server with a 30s timeout. - linear uses SSE (url) with an auth header. - docs uses streamable HTTP (httpUrl) with a shorter timeout and custom header. This structure matches the official docs (e.g., a user provided example for HTTP server integration)[85]. Note that you should not use both url and httpUrl for one entry – pick the correct one based on the server’s capability. If this distinction is missed, the CLI might mis-handle the connection (earlier versions lacked httpUrl support, causing HTTP endpoints to fail to connect[86][87], but as of recent updates httpUrl is fully supported[88][85]). • Installation of MCP Server Dependencies: Gemini CLI doesn’t automatically install local MCP server packages – it assumes if you provide a command (like npx or a binary name), you have the means to execute it. However, many community MCP servers are distributed via npm or similar. The Gemini CLI docs acknowledge that if a tool’s functionality is available natively (e.g., the user already has git installed, you might not need a Git MCP server)[89]. But for custom servers (like a GitHub MCP server with extended capabilities), you’ll likely use npx to run it on-demand. For instance, adding the GitHub MCP as remote vs local: • Remote: You could do gemini mcp add --transport http github https://github-mcp.example.com/mcp --header "Authorization: token ". • Local via npx: gemini mcp add github -- npx -y @github/mcp-server (hypothetical package name) to auto-install and run. Integration tip: The -y flag in npx auto-confirms installation. This is convenient but note it will install anew each run. To reduce startup latency, users can globally install the MCP server (npm install -g ...) and then use the installed command in config. For example, one Reddit user found they needed to adjust the command name for Puppeteer’s server on WSL (installing mcp-server-puppeteer globally and using that command)[90][91]. Document such nuances for Windows/WSL users – e.g., add "cmd" wrapper if needed, or ensure node_modules/.bin is in PATH. Supported Protocols and Communication Gemini CLI supports stdio, SSE, and HTTP transports natively[61], similar to Cursor but with explicit config flags. The internal architecture has a Discovery layer and Execution layer dedicated to MCP[92][61]: • Discovery Phase: On Gemini CLI startup (or when configuration changes), it runs discoverMcpTools() which iterates through each configured server in mcpServers[93]. It attempts to establish a connection: • For a stdio server, it spawns the process and waits for the JSON-RPC handshake on stdout[94]. • For SSE, it opens the SSE stream (GET request to the url)[95] and waits for the endpoint event to finalize the handshake. • For HTTP, it likely performs an initial HTTP POST to the httpUrl or uses a similar upgrade mechanism[95] (the spec indicates a single endpoint; Gemini’s implementation uses separate config keys but ultimately uses the unified approach). During discovery, the CLI calls the tools/list method on each server to fetch available tool definitions (name, description, parameters)[93]. It then sanitizes and registers these tools in its global tool registry, handling any name conflicts by namespacing or renaming if needed[96]. Integration: Alph CLI can adopt a similar approach: at startup, iterate configured servers, connect (perform MCP handshake), retrieve tools and prompts offered, and make them available to the CLI’s command set. The conflict resolution is important if two servers offer a tool with the same name – Gemini CLI’s approach ensures one doesn’t override the other inadvertently[96]. • Execution Phase: Each tool from an MCP server is represented internally as a DiscoveredMCPTool instance[97]. When the user invokes a command that maps to an MCP tool (either automatically via the AI agent or manually via a slash command), the CLI will: • Confirm permission – If the server is not trusted ("trust": false by default), Gemini will prompt the user for confirmation before executing a potentially sensitive tool call[98]. For example, if a tool is about to delete a file, the CLI asks the user. If "trust": true for that server, it skips confirmation for speed[82]. Alph CLI should implement similar confirmation logic or allow a “trusted” setting per server for user safety. • Execute the call – The CLI sends a JSON-RPC request (tools/execute with tool name and params) to the MCP server over the established transport[99]. This is abstracted away from the user – they just see that the tool runs. • Stream the response – Gemini CLI processes responses, whether a full result or incremental output. SSE and HTTP-streaming responses arrive as events/chunks, which the CLI concatenates or displays progressively. In practice, the CLI will typically wait for the final JSON result of a tool and then print any output or use it to formulate the assistant’s reply to the user[99]. If a server sends notifications (like logging events or progress updates), Gemini CLI can handle those too (the architecture mentions handling logging, etc.) but by default those might be suppressed or shown in verbose mode. • Concurrent usage: Gemini CLI can maintain multiple MCP connections simultaneously (one per configured server). It handles state per connection (including any session IDs for SSE). If multiple tools are called in one user request, the CLI will sequence them as needed (the ReAct loop decides the order). Alph CLI should ensure thread-safe or async-safe handling of each server channel. • Protocols in Config: As noted, use url for SSE and httpUrl for HTTP in settings.json. An incorrect choice will lead to connection failure. For example, a Reddit user initially noted Gemini CLI only supported SSE and would fail for streamable HTTP, but within weeks, the CLI added support – using the httpUrl key is the indicator of that support[100][88]. Now, an example working config from a user for HTTP is: "mcpServers": { "httpServer": { "httpUrl": "http://localhost:8000/weather/mcp/", "timeout": 5000 } } which successfully connected[88][85]. Ensure Alph CLI documentation uses the correct key depending on server type when guiding users. Authentication & Security in Gemini CLI Gemini CLI provides robust support for authenticated MCP servers: • OAuth 2.0: For remote servers requiring OAuth (e.g., third-party APIs like Google Drive), Gemini CLI can auto-discover OAuth and handle token flows[101][102]. If you add a server without providing tokens and it returns 401 Unauthorized, the CLI will: • Discover the authorization and token endpoints from the server’s metadata (MCP servers can expose OAuth info)[103]. • Launch a browser for the user to log in (it requires a local browser; headless servers won’t support this)[104]. • Receive the OAuth redirect at http://localhost:7777/oauth/callback (Gemini CLI runs a temporary local server for this callback)[105]. • Exchange the code for tokens and store them in ~/.gemini/mcp-oauth-tokens.json securely[106]. • Reconnect to the MCP server with the Bearer token in the Authorization header automatically. All of this is done after a simple gemini mcp add if the server supports dynamic OAuth. For example, adding asana as shown in docs triggers an OAuth flow[107][107]. Alph CLI can trust Gemini CLI to manage this when users integrate those services. However, if Alph CLI were to implement its own MCP client, supporting OAuth would be a significant task – likely reusing a similar approach (local webserver for callback, etc.). In most cases, it’s acceptable to instruct users to use Gemini CLI’s capabilities for OAuth-enabled servers or to perform an initial login via Gemini CLI or Claude and then use the obtained token manually for Alph CLI (noting token locations). • Manual Tokens (Headers): Gemini CLI allows specifying static headers on a per-server basis. Using the CLI: -H "X-Api-Key: value" can be given multiple times[108][109]. In settings.json, these appear under the server as a "headers": {} object[110]. This is useful for API-key auth. Alph CLI should incorporate a similar mechanism – e.g., allow users to provide custom headers for their MCP endpoints (since different services use different header names for keys/tokens). The example above with secure-http shows adding a Bearer token via header[79]. • Google Cloud Credentials: A special case – Gemini CLI supports using Google Application Default Credentials for Google Cloud-based MCP servers by setting "authProviderType": "google_credentials" in the config[111][112]. This will make the CLI pick up credentials from the environment (e.g., service account keys or user ADC) instead of a user login. It’s an advanced feature likely not needed for Alph CLI unless integrating deeply with GCP. But if relevant, one can configure: { "mcpServers": { "myGCPServer": { "httpUrl": "https://my-cloud-run.app/mcp", "authProviderType": "google_credentials", "oauth": { "scopes": ["https://www.googleapis.com/auth/cloud-platform"] } } } } so that Gemini uses the local Google auth context[113][112]. Alph CLI may not implement this unless it’s running in GCP environments; it’s acceptable to note it as not supported if out of scope. • Trust & Permissions: The trust flag (per server) can be set to true to bypass all confirmation prompts for tool usage[114][115]. By default it’s false, meaning Gemini will ask user consent when an MCP tool is invoked for the first time in a session (especially if it’s doing file writes or other sensitive ops). As integration engineers, decide if Alph CLI will allow a similar “always trust this server” setting. Given many users appreciate convenience, having an opt-in trust flag is wise (Gemini CLI exposes it via the --trust option on mcp add[116]). But make sure to communicate the security implications. • Sandboxing: One unique aspect: Gemini CLI often runs in sandboxed modes (especially when invoked from Cloud Shell or VS Code). The docs note that when operating in a sandbox (Docker), any tools or MCP servers must exist inside that container environment[117]. This means if Gemini CLI is being used in a locked-down environment (no internet, pre-installed tools only), one must include the MCP server executables in the sandbox image. For Alph CLI: If you have a similar “sandbox” or offline mode, document that the MCP servers must either be accessible within that environment or use an escape hatch. In most cases, Alph CLI might not sandbox as strictly, but be aware if users are on a containerized or remote VM scenario. Usage and Runtime Behavior • Lifecycle & Latency: Gemini CLI keeps MCP server connections alive for the duration of the CLI session. For stdio, the process remains running in the background, which avoids repeated startup costs. For SSE/HTTP, persistent connections are maintained (with reconnection logic if dropped). The typical overhead for the initial handshake is small (a few JSON messages). Subsequent calls have latency primarily defined by the server’s response time and network. The CLI’s default request timeout is 600,000 ms (10 minutes)[118], which is quite generous to accommodate long-running tools. This can be overridden per server as shown above. Alph CLI should consider implementing a similar timeout and perhaps a shorter default (10 minutes is to ensure even very heavy operations succeed; if Alph CLI expects shorter operations, it might choose a smaller default but allow override). If a call exceeds the timeout, Gemini CLI will cancel it and log an error. It does not automatically retry; it relies on the user to re-invoke or the agent to handle the failure. • Retries: By default, Gemini CLI doesn’t retry MCP requests on failure (e.g., a transient network error). It surfaces the error to the user or in the agent’s reasoning. For integration, this means Alph CLI should capture any exceptions from an MCP call and decide whether to retry or not. In line with Gemini, an initial approach is to not retry automatically, to avoid unintended side effects (e.g., running the same database query twice). Instead, handle errors gracefully and perhaps inform the user or agent so they can choose to retry. • Output Handling: When a tool executes, the CLI prints relevant information. For example, it might show something like: ✓ stdio-server: ... - Connected ✓ http-server: ... - Connected ✗ sse-server: ... - Disconnected as in the list output[74]. During execution, if a tool produces a result, the CLI will either display it directly or incorporate it into the final answer. Integration engineers should note how to parse the results. Gemini CLI will combine the model’s response with any tool outputs. In Alph CLI, you might separate these concerns (e.g., print the tool output first, then the AI’s message). Observing Gemini’s behavior for commands like /tools and actual use of a tool (maybe via the --verbose flag if available) can guide how much to expose. • Error Logging: The CLI likely logs MCP errors to stderr. If a server fails to initialize (say the process exits or sends malformed JSON), you’ll see an error in the console (and possibly in the .gemini log if one exists). There’s an indication that Gemini CLI might output connection status in the gemini mcp list (servers marked “Disconnected” if e.g. handshake failed)[74]. Alph CLI should similarly track which servers are currently connected vs had errors, and provide a listing to the user. For debugging, instruct users to run the CLI with any verbose or debug flags to see underlying errors if needed. • MCP Prompts as Commands: A newer Gemini CLI feature is treating MCP prompts as slash commands[119]. If an MCP server exposes prompts (templated workflows), Gemini CLI will list them as available /mcp__name__prompt commands in the CLI chat interface[120]. For example, if a server provides a prompt “refactor-code”, you might invoke it with /mcp__myserver__refactor-code --args.... Alph CLI integration can mirror this by listing available prompts and allowing users to call them easily. This provides a more integrated feel (the user doesn’t have to manually craft a request to use a prompt; it’s advertised as a command). The Google Cloud blog notes that Gemini’s VS Code extension surfaces these in the palette as well[121]. • Concurrency & Threading: If a user triggers multiple tool calls in parallel (not common in CLI, but possible in agent mode), Gemini CLI’s core should handle it by queuing or simultaneous awaits. Each MCP transport in the core appears to be managed independently, but there is likely a global lock when the LLM is “thinking”. Practically, the agent calls one tool at a time in a ReAct loop. Alph CLI can assume one active tool execution at any given moment per conversation. However, if Alph CLI offers a manual way to run a tool outside of the agent loop, ensure it doesn’t conflict with an ongoing agent call. • Sandbox Behavior: If running in Cloud Shell or a Docker sandbox, remember to install MCP servers in that environment as mentioned. The Gemini CLI docs highlight that in sandbox mode, commands like npx must be available inside the sandbox container[122]. If a user tries to run an MCP that isn’t present, they’ll get an error. Integration documentation should explicitly mention, e.g., “In Cloud Shell or containerized environments, pre-install any required MCP server packages inside the environment. For example, add npm install -g @modelcontextprotocol/server-XYZ to your Dockerfile for each server or use gemini mcp add inside the container.” • Example Session: To illustrate: suppose a user adds a “GitHub” MCP server that allows creating a GitHub issue. In Gemini CLI, after adding and authenticating, the user might type: “/mcp__github__create_issue --repo myorg/myrepo --title 'Bug Report' --body 'There is a bug.'”. The CLI will confirm (if not trusted) and execute the call. The output from the tool (e.g. new issue URL) will be shown or used by the model to respond. If Alph CLI aims to provide a similar user experience, it should ensure MCP tools can be invoked with clear syntax and that their outputs are either displayed or fed back into the AI’s response.