Add a remote MCP server to Gemini CLI
Gemini CLI reads MCP servers from mcpServers in settings.json. For a Streamable HTTP server the key is httpUrl: url means an SSE server. Google's docs note that Gemini CLI was replaced by Antigravity CLI on June 18, 2026, which has its own page here.
By Jake Marsh. Checked against Gemini CLI's own docs on 2026-10-31; each section links its source.
The Gemini CLI config
For a server named my-server at https://example.com/mcp that takes an Authorization header. Where it goes: ~/.gemini/settings.json (or .gemini/settings.json in the project).
{
"mcpServers": {
"my-server": {
"httpUrl": "https://example.com/mcp",
"headers": {
"Authorization": "Bearer YOUR_KEY"
}
}
}
}Swap in your own server below and the Gemini CLI version updates first, with every other client after it.
Where Gemini CLI reads it
~/.gemini/settings.jsonuser: every project.gemini/settings.json in the projectproject: that project (the default scope for gemini mcp add)
Keys, headers and sign-in
Static keys go in headers, which works with both url and httpUrl. From the terminal: gemini mcp add --transport http --header "Authorization: Bearer ..." <name> <url>, with -s user to write the user file.
Environment variable expansion ($VAR or ${VAR}) is documented for a server's env block, which is passed to stdio servers. For OAuth servers, /mcp auth <name> signs in; tokens are kept in ~/.gemini/mcp-oauth-tokens.json.
Check that it connected
gemini mcp list shows each server's configuration and connection status. In a session, /mcp shows status, a configuration summary and the available tools.
Gemini CLI gotchas
httpUrl selects Streamable HTTP and url selects SSE. A Streamable HTTP endpoint written as url connects with the wrong transport.
Avoid underscores in server names (my-server, not my_server). Tool names become mcp_<server>_<tool>, and the policy parser splits on the first underscore after mcp_, so wildcard rules and policies fail silently.
gemini mcp add defaults to project scope. Without -s user the server exists only in that project's .gemini/settings.json.
OAuth needs a local browser and a localhost redirect, so it doesn't work in headless or containerized environments without browser support.
Still not connecting? Gemini CLI MCP server not loading walks through the fixes in order.
Generate the config for your server
Runs in your browser. Nothing you type is sent anywhere. Still, don't paste real keys on shared screens.
Gemini CLI
~/.gemini/settings.json (or .gemini/settings.json in the project)
{
"mcpServers": {
"my-server": {
"httpUrl": "https://example.com/mcp",
"headers": {
"Authorization": "Bearer YOUR_KEY"
}
}
}
}Claude Code
Run in a terminal (--scope user makes it available in every project)
claude mcp add --transport http --scope user my-server "https://example.com/mcp" --header "Authorization: Bearer YOUR_KEY"Source: code.claude.com/docs/en/mcp
Cursor
~/.cursor/mcp.json (all projects) or .cursor/mcp.json (one project)
{
"mcpServers": {
"my-server": {
"url": "https://example.com/mcp",
"headers": {
"Authorization": "Bearer YOUR_KEY"
}
}
}
}Source: cursor.com/docs/context/mcp
Codex CLI
~/.codex/config.toml
[mcp_servers.my_server]
url = "https://example.com/mcp"
http_headers = { "Authorization" = "Bearer YOUR_KEY" }Source: developers.openai.com/codex/mcp
Windsurf / Devin Desktop
~/.config/devin/mcp_config.json (older Windsurf: ~/.codeium/windsurf/mcp_config.json)
{
"mcpServers": {
"my-server": {
"serverUrl": "https://example.com/mcp",
"headers": {
"Authorization": "Bearer YOUR_KEY"
}
}
}
}Devin CLI / Devin Local
Run in a terminal (-s user saves it to ~/.config/devin/mcp_config.json for every project)
devin mcp add -s user -H "Authorization: Bearer YOUR_KEY" my-server "https://example.com/mcp"VS Code (Copilot agent mode)
.vscode/mcp.json in the workspace, or your user mcp.json (MCP: Open User Configuration)
{
"servers": {
"my-server": {
"type": "http",
"url": "https://example.com/mcp",
"headers": {
"Authorization": "Bearer YOUR_KEY"
}
}
}
}Source: code.visualstudio.com/docs/agents/reference/mcp-configuration
Antigravity CLI (agy)
~/.gemini/config/mcp_config.json (or .agents/mcp_config.json in the workspace)
{
"mcpServers": {
"my-server": {
"serverUrl": "https://example.com/mcp",
"headers": {
"Authorization": "Bearer YOUR_KEY"
}
}
}
}Source: antigravity.google/docs/mcp
Cline
cline_mcp_settings.json (in the Cline panel, MCP Servers > Configure > Configure MCP Servers; Cline CLI: ~/.cline/data/settings/cline_mcp_settings.json)
{
"mcpServers": {
"my-server": {
"type": "streamableHttp",
"url": "https://example.com/mcp",
"headers": {
"Authorization": "Bearer YOUR_KEY"
}
}
}
}Source: docs.cline.bot/mcp/mcp-overview
OpenCode
opencode.json in the project root, or ~/.config/opencode/opencode.json for every project
{
"$schema": "https://opencode.ai/config.json",
"mcp": {
"my-server": {
"type": "remote",
"url": "https://example.com/mcp",
"oauth": false,
"headers": {
"Authorization": "Bearer YOUR_KEY"
}
}
}
}Source: opencode.ai/docs/mcp-servers/
Need a task list for those agents?
Taskhold is a remote MCP server that gives Gemini CLI and your other agents a task list you share, with their progress on a live board. Its setup link writes this config for the agent, so you don't have to. $12 a month or $120 a year, 7-day trial.