Gemini CLI MCP server not loading from settings.json: the fixes

Start with /mcp list

Gemini CLI keeps MCP connection errors silent at startup and shows a single hint instead: "MCP issues detected. Run /mcp list for status." Run /mcp list in the session, or gemini mcp list from a shell, to see each server as CONNECTED, CONNECTING or DISCONNECTED, with its error and its tools. Detailed errors for a server also come back when the model tries one of its tools.

For more detail, start Gemini CLI with --debug and press F12 in interactive mode to open the debug console. Gemini CLI captures each stdio server's stderr and logs it.

Gemini CLI never reads the server

• Servers go in an mcpServers object in ~/.gemini/settings.json (every session) or .gemini/settings.json in the project root (that project only). Project settings override user settings, and a system settings file overrides both.
• gemini mcp add writes to the project file unless you pass -s user, so a server added from one folder won't load in another.
• gemini mcp add also defaults to the stdio transport. Add a remote server with --transport http (or sse), or its URL is taken as a command to run.
• url means an SSE endpoint, httpUrl means Streamable HTTP, and command means stdio. When more than one is set, httpUrl wins, then url. A server that only speaks Streamable HTTP won't connect under url.
• mcp.allowed limits Gemini CLI to the server names it lists, and mcp.excluded skips names. An admin can turn MCP off entirely with admin.mcp.enabled.
• A disabled server shows as Disabled in /mcp and doesn't connect. gemini mcp enable <name> (or /mcp enable <name>) turns it back on; the state is kept in ~/.gemini/mcp-server-enablement.json.

{
  "mcpServers": {
    "my-remote": {
      "httpUrl": "https://mcp.example.com/mcp",
      "headers": { "Authorization": "Bearer $MY_SERVICE_TOKEN" }
    },
    "my-local": {
      "command": "npx",
      "args": ["-y", "some-mcp-server"],
      "env": { "API_KEY": "$API_KEY" }
    }
  }
}

Folder trust blocks every server

Gemini CLI's Trusted Folders feature is off by default. When it's on and a folder is marked Don't trust, Gemini CLI runs in safe mode there: it ignores the project's .gemini/settings.json and .env files and connects no MCP servers at all. Run /permissions to change the current folder's trust; decisions are stored in ~/.gemini/trustedFolders.json.

gemini mcp list tests stdio servers and reports them as Connected only when the current folder is trusted, and as Disconnected otherwise. gemini trust trusts the current folder. In CI, --skip-trust or GEMINI_CLI_TRUST_WORKSPACE=true trusts the workspace for that run.

The server starts without its variables

• Gemini CLI removes sensitive variables from the environment it hands to MCP servers: GEMINI_API_KEY, GOOGLE_API_KEY and any name matching *TOKEN*, *SECRET*, *PASSWORD*, *KEY*, *AUTH* or *CREDENTIAL*. A server that reads GITHUB_TOKEN from your shell gets nothing unless you name it in the server's env block, for example "GITHUB_TOKEN": "$GITHUB_TOKEN".
• A variable that isn't set resolves to an empty string, so a missing export sends an empty value instead of raising an error.
• Run the command by hand to check that it starts, and set cwd if the server expects to run from a particular folder.
• Leave underscores out of server names. Tools are named mcp_<server>_<tool>, and the policy engine splits on the first underscore after mcp_, so a name like my_server can make allow and deny rules fail silently. Use my-server.

Sign-in and confirmations

• Gemini CLI supports OAuth for remote servers. A server that answers 401 starts discovery, dynamic client registration and a browser sign-in. /mcp auth lists servers that need it, and /mcp auth <name> signs in again when tokens expire.
• OAuth sign-in needs a local browser and a redirect to http://localhost:<port>/oauth/callback, so it fails over SSH without X11 forwarding, in headless environments and in containers without a browser. Send a token in headers there.
• Gemini CLI asks before each MCP tool call unless the server is trusted. "trust": true (or gemini mcp add --trust) skips every confirmation for that server, and includeTools or excludeTools narrows what the model sees.
• A tool that is found but fails can be a timeout. The per-server timeout defaults to 600,000 ms (10 minutes) and is set with timeout.

Taskhold-specific checks

Taskhold is a remote Streamable HTTP server at https://taskhold.com/api/mcp. When the taskhold tools don't show up in Gemini CLI, check these in order:

1. The entry uses httpUrl, not url, set to https://taskhold.com/api/mcp. A setup URL from Settings, pasted into Gemini CLI with "set this up", writes the entry for you, or add it with the command below.
2. The header is Authorization: Bearer followed by a key that starts with atd_sk_. Taskhold's 401 names the cause: missing_key, bad_header, not_a_taskhold_key or unknown_key. Using "Bearer $TASKHOLD_API_KEY"? Export the variable in the shell that starts Gemini CLI.
3. Sign-in without a key (OAuth) is set up for Claude Code, Cursor, Codex, claude.ai and ChatGPT. In Gemini CLI, send the key in the header. With no header, /mcp can list taskhold and its tools, but every call comes back 401 missing_key.
4. A 402 means the key works but the trial ended or the plan was canceled. Restart the plan and the same config works again.
5. Name the server taskhold, with no underscore, and choose Always allow this server (or set trust) so progress reports don't stop on a prompt each time. Settings in Taskhold shows Connected after the first call.

gemini mcp add -s user --transport http --header "Authorization: Bearer <your atd_sk_ key>" taskhold https://taskhold.com/api/mcp

With the tools loaded and the GEMINI.md snippet from the Gemini CLI page, every task Gemini CLI starts, its steps and its questions show on the live board next to your other agents. The same checks for other clients: Codex CLI, Windsurf and Claude Code.