MCP Config Locations for Coding Agents: Claude, Codex, Cursor, and GitHub Copilot

MCP configuration is not stored in one universal place. Claude Code, Codex, Cursor, and GitHub Copilot each decide where they read server definitions. If a server is not showing up, open the host-specific config first: .mcp.json for Claude project sharing, config.toml for Codex, .cursor/mcp.json for Cursor, and GitHub.com repository settings for Copilot cloud agent.

Quick answer: where to configure MCP

The mental model is simple: MCP is the protocol, but the coding agent is the host. The host owns discovery, file format, approval behavior, and secret handling.

What MCP config actually controls

An MCP config tells the host how to reach a server. For a local stdio server, that usually means a command, arguments, working directory, and environment variables. For a remote server, it usually means a URL plus headers, OAuth, or bearer-token configuration.

The config does not guarantee that a tool will appear. A server can be configured correctly and still fail later because the command cannot start, a token is missing, the transport is wrong, or the server exposes resources and prompts but no tools. Treat config as the first layer, not the whole integration.

Claude Code MCP config locations

Claude Code has three everyday MCP scopes:

Use the CLI when possible because it writes the correct shape:

claude mcp add --transport stdio filesystem --scope local -- npx -y @modelcontextprotocol/server-filesystem .
claude mcp add --transport http sentry --scope user https://mcp.sentry.dev/mcp
claude mcp add --transport http docs --scope project https://developers.openai.com/mcp

A project-scoped .mcp.json uses an mcpServers object:

{
  "mcpServers": {
    "shared-docs": {
      "type": "http",
      "url": "https://developers.openai.com/mcp"
    }
  }
}

Claude Code prompts before using project-scoped servers from .mcp.json. That approval step matters in real teams: a teammate may pull the file and still see the server as pending until they approve it.

Codex MCP config locations

Codex stores MCP configuration in config.toml. The default user-level file is:

~/.codex/config.toml

Codex can also read project-scoped config from:

<project-root>/.codex/config.toml

Project-scoped config only loads in trusted projects. That trust gate is intentional: a repository config can ask Codex to start local processes, forward environment variables, or connect to remote services.

Codex uses TOML, not JSON. Each MCP server gets a [mcp_servers.<server-name>] table:

[mcp_servers.context7]
command = "npx"
args = ["-y", "@upstash/context7-mcp"]
startup_timeout_sec = 20
tool_timeout_sec = 60

[mcp_servers.openaiDeveloperDocs]
url = "https://developers.openai.com/mcp"

Common copy-paste mistake: using Claude or Cursor's mcpServers JSON shape inside Codex. Codex expects the snake-case TOML table name mcp_servers, so [mcp.servers.foo] ou { "mcpServers": ... } will not load as a Codex MCP server.

Cursor MCP config locations

Cursor uses mcp.json files:

~/.cursor/mcp.json
<project-root>/.cursor/mcp.json

Use the global file for personal tools and the project file for repo-specific tools. A typical Cursor config looks like this:

{
  "mcpServers": {
    "repo-docs": {
      "command": "npx",
      "args": ["-y", "@upstash/context7-mcp"],
      "env": {
        "API_KEY": "value"
      }
    }
  }
}

If this is committed, do not commit actual token values. Prefer environment variable names, documented setup steps, or a checked-in example file when each developer must provide their own credential.

GitHub Copilot cloud agent MCP behavior

GitHub Copilot cloud agent is different from local desktop agents. Repository administrators configure MCP servers in GitHub.com repository settings, under the Copilot MCP servers page. The JSON is entered into GitHub's UI and validated when saved.

GitHub's config uses an mcpServers object, but each server must specify the tools it exposes to the agent. GitHub recommends allowlisting specific read-only tools because Copilot cloud agent can use MCP tools autonomously and does not ask for approval before each tool call.

Example shape:

{
  "mcpServers": {
    "internalDocs": {
      "type": "http",
      "url": "https://docs.example.com/mcp",
      "tools": ["search_docs", "read_page"]
    }
  }
}

Secrets and variables for this path must use GitHub's Copilot agent secret and variable model. Referenced names must use the COPILOT_MCP_ prefix. Do not assume your local shell environment exists inside the cloud agent.

Local vs remote MCP servers

Local stdio servers are started as subprocesses by the host. They are useful when the server needs filesystem access, a local CLI, a local database tunnel, or a development-only service.

Remote HTTP servers are independent services at a URL. They are better for shared services, OAuth-backed tools, and systems that should not run on each developer's laptop.

The MCP transport spec expects stdio servers to communicate over standard input and standard output, while Streamable HTTP servers expose an HTTP endpoint. That difference affects debugging: a broken local command is not the same class of problem as a bad remote URL.

What should be committed

Commit shared MCP config only when it is safe and useful for the whole team.

Commit:

• Project-scoped server names and non-secret URLs.
• Commands that every contributor can run.
• Environment variable names, not values.
• Tool allowlists for shared remote servers.
• Comments in adjacent docs explaining how to create required tokens.

Do not commit:

• Personal access tokens.
• Local absolute paths such as /Users/alex/dev/private-server.
• Experimental servers that only one developer uses.
• Broad write-capable tool allowlists without a team review.
• Headers containing static secrets.

A good team pattern is to commit the project config only when the same server should load for everyone, then keep credentials in user scope, environment variables, a secrets manager, or host-specific secret storage.

Environment variables and secrets

Environment variables behave differently in shells, GUI apps, remote agents, and CI-like cloud environments. If an MCP server works in your terminal but not in the agent, the config may be fine while the host process has a different environment.

Use these checks:

which node
which npx
which uvx
printenv GITHUB_TOKEN

Then compare that with how the host starts the server. For local agents, absolute command paths often remove ambiguity:

{
  "mcpServers": {
    "local-tool": {
      "command": "/opt/homebrew/bin/node",
      "args": ["./server.js"],
      "env": {
        "API_KEY": "${API_KEY}"
      }
    }
  }
}

For Copilot cloud agent, use GitHub's required COPILOT_MCP_ secret and variable prefix instead of assuming local environment variables.

What goes wrong in real projects

The most common failure is copying a working server example into the wrong host format. Claude and Cursor examples often use JSON with mcpServers; Codex uses TOML with [mcp_servers.<name>]. That one difference is enough to make a server disappear.

The second failure is putting a team config in a personal location. A Claude local-scope server in ~/.claude.json will not help a teammate, even if it works perfectly on your machine.

The third failure is committing too much. A project .mcp.json ou .cursor/mcp.json can be a good team artifact, but only when it avoids secrets, private paths, and broad write tools.

The fourth failure is expecting Copilot cloud agent to behave like a local IDE. Its repository MCP config is controlled through GitHub settings, supports MCP tools, and uses GitHub-managed secrets and variables. A local ~/.cursor/mcp.json ou ~/.codex/config.toml has no effect there.

Final verification checklist

• Identify the host first: Claude Code, Codex, Cursor, or GitHub Copilot cloud agent.
• Open the correct config location for that host.
• Confirm the file format: JSON for Claude and Cursor, TOML for Codex, GitHub settings JSON for Copilot.
• Keep shared project configs free of secrets and machine-specific paths.
• Use user-scoped config for private tokens and personal servers.
• Run the host's inspection command or UI after editing.
• Restart the host if it does not live-reload MCP config.
• Confirm the server appears, then confirm it exposes the tools you expect.