Configuring MCP Servers

Reads MCP servers from a single JSON file. Three ways to edit it: the in-app menu, the file directly, or via the Extensions marketplace.

Option 1, in-app shortcut (easiest). Open Claude Desktop, go to Settings → Developer → Edit Config. This opens the config file in your default editor and creates it if it doesn't exist. Add your server, save, and fully quit and reopen Claude Desktop (not just close the window).

Option 2, edit the file directly. The config lives at:

A minimal example that gives Claude Desktop access to your Desktop and Downloads folders:

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/Users/you/Desktop",
        "/Users/you/Downloads"
      ]
    }
  }
}

Restart the app. If everything worked, the new tools appear in the chat input area.

Option 3, Desktop Extensions. Claude Desktop also supports packaged MCP servers distributed as .mcpb files. They install with a double-click from the in-app Extensions marketplace, no JSON editing required. Good for non-technical users; the JSON method is better when you need custom servers or full control.

CLI-driven, so you'll mostly use the claude mcp command family rather than editing files by hand.

$ claude mcp add my-database -- \
    npx -y @modelcontextprotocol/server-postgres postgresql://localhost/mydb

$ claude mcp add --transport http craft https://mcp.craft.do/my/mcp

$ claude mcp add my-server \
    -e API_KEY=sk-abc123 \
    -e DATABASE_URL=postgres://localhost/db \
    -- node /path/to/server.js

$ claude mcp add-json weather-api '{"type":"http","url":"https://api.weather.com/mcp","headers":{"Authorization":"Bearer token"}}'

$ claude mcp list              # show all configured servers
$ claude mcp get my-server     # show details for one
$ claude mcp remove my-server  # delete it

Inside an active Claude Code session, type /mcp to see status and handle OAuth logins for servers that need them.

Same pattern as Claude Code, with a different command name and a different file.

$ gemini mcp add my-server -- /path/to/server arg1 arg2

Useful flags:

• -s, --scope, user or project (see scoping section below).
• -H, --header, HTTP headers, e.g. -H "Authorization: Bearer abc123".
• --timeout, connection timeout in milliseconds.
• --trust, skip tool-call confirmation prompts (use carefully).
• --include-tools / --exclude-tools, allow/deny specific tools from a server.
• --description, a short description for your own reference.

Or edit the JSON directly. Gemini CLI reads from ~/.gemini/settings.json (user) or .gemini/settings.json (project). The block looks like this:

{
  "mcpServers": {
    "git": {
      "command": "uvx",
      "args": ["mcp-server-git"]
    },
    "github": {
      "httpUrl": "https://api.githubcopilot.com/mcp/",
      "headers": {
        "Authorization": "Bearer YOUR_GITHUB_TOKEN"
      },
      "timeout": 5000
    }
  }
}

Environment variables in the env block are expanded automatically, you can reference ${VAR} and Gemini CLI will substitute from your shell environment. Inside a session, /mcp lists everything that connected successfully.

Uses TOML, not JSON, and the CLI and IDE extension share a single config file. This is convenient, configure once, use everywhere, but a syntax error breaks both.

$ codex mcp add context7 -- npx -y @upstash/context7-mcp

$ codex mcp add my-server --env API_KEY=xyz -- /path/to/server

Or edit ~/.codex/config.toml directly:

[mcp_servers.tooluniverse]
command = "uvx"
args = ["--refresh", "tooluniverse"]

[mcp_servers.tooluniverse.env]
PYTHONIOENCODING = "utf-8"

Open the config from the IDE extension: click the gear icon → Codex Settings → Open config.toml.

$ codex mcp list      # show all servers
$ codex mcp get NAME  # show one
$ codex mcp remove NAME
$ codex mcp login NAME   # OAuth login for HTTP servers that need it
$ codex mcp logout NAME

Inside a TUI session, /mcp shows the active servers.

There's only one scope: the user, on this machine. Every server in claude_desktop_config.json is global to that user's Claude Desktop install. No per-project setup, no team-shared file. If you want a colleague to have the same server, you send them the config and they paste it into theirs.

Set the scope when adding:

$ claude mcp add --scope project shared-db -- npx -y my-db-server
$ claude mcp add --scope user my-personal-tool -- node /path/to/tool.js

Precedence when names collide: local > project > user. So a local-scope server with the same name as a project one will win for you, without affecting your teammates.

Project scope is gated by trust. When you clone a repo with a .mcp.json file, Claude Code won't silently start running other people's servers, it shows them as ⏸ Pending approval until you accept the workspace trust dialog. This is the right default; review what's in .mcp.json before approving.

Simpler: just user and project (sometimes called "workspace").

Set the scope when adding:

$ gemini mcp add --scope user my-tool -- /path/to/tool
$ gemini mcp add --scope project team-tool -- /path/to/team-tool

When the same server name appears in both, project overrides user for that workspace.

The richest model. There are two places MCP servers can live, plus a layering system that affects all config (not just MCP):

Resolution order (highest precedence wins): CLI overrides → project config (closest to current directory wins if there are multiple) → profile → user config.

Claude Code: --scope user. Gemini CLI: --scope user. Codex: user config (~/.codex/config.toml). Claude Desktop: it's already the only scope, so just add it.

Claude Code: --scope project, commit .mcp.json. Gemini CLI: --scope project, commit .gemini/settings.json. Codex: commit .codex/config.toml. Never commit API keys, use environment variable references (${API_KEY}) and document which variables team members need to set.

Claude Code: default local scope. Gemini CLI / Codex: project scope (and .gitignore the file if you don't want to commit it).

Codex profiles are purpose-built for this. The other tools achieve the same effect with project-scoped configs in separate directories.