Claude Code MCP servers can be configured in several places, and “Claude Desktop” can mean its chat surface or its local Code tab. Start by identifying which surface should load the server and whether the config is personal, project-specific, or team-shared. Anthropic’s current MCP and Desktop docs were checked November 3, 2026.

Which MCP file belongs to which scope?

In MCP terminology, local scope does not mean a file named settings.local.json: it is stored under the current project entry in ~/.claude.json. The project-shared file is .mcp.json. These are server definitions, separate from permission rules in settings JSON.

Does Claude Desktop share MCP config with the CLI?

Partly, depending on the surface. Anthropic’s current Desktop docs say local Code tab sessions load servers from the Desktop config file as well as ~/.claude.json and the project’s .mcp.json. A server in the Desktop file is also available to Desktop chat. The standalone CLI does not read the Desktop file; on macOS and WSL, Anthropic documents claude mcp add-from-claude-desktop as an import path into Claude Code’s config.

There is also a documented precedence difference: if a local Desktop Code session sees the same stdio server name at the top level of ~/.claude.json and in .mcp.json, Desktop Code uses the user-scope definition. For the standalone CLI, Anthropic documents local, then project, then user scope precedence. Do not assume that a server’s identical name means every surface resolves the same definition.

How do I choose the CLI scope?

• Use the default local scope for a personal server needed only in the current project. It is stored in ~/.claude.json under that project path, so it is not committed.
• Use project scope for a reviewed server definition teammates should receive with the repository. It is written to .mcp.json; interactive sessions ask for approval before using project servers.
• Use user scope for a personal utility server available across your projects.

# See configured servers and their connection status
claude mcp list

# Add a project-shared HTTP server
claude mcp add --transport http team-service --scope project https://mcp.example.com/mcp

# Import Desktop servers where supported, then inspect the result
claude mcp add-from-claude-desktop
claude mcp list

The example endpoint is a placeholder, not a real service. Import is documented for macOS and Windows Subsystem for Linux; the command reads Desktop’s configuration from its standard location and offers a server-selection prompt. Verify names and status after import.

What should I check when a server appears in one surface only?

1. Write down the exact surface: Desktop chat, Desktop Code tab, or standalone CLI. Also note whether the session is local, SSH, or cloud-hosted.
2. Run claude mcp list in the CLI or /mcp in an interactive Code session. These show what that Claude Code session has loaded; a missing entry does not establish which other app config was read.
3. Check the scope and file: project servers use the repository’s .mcp.json; local and user servers use ~/.claude.json; Desktop chat uses the Desktop config.
4. For a name collision, compare the complete server entries and the surface-specific precedence rules. Test with a unique temporary server name in a non-sensitive project if you need to isolate which entry is active.
5. For remote or SSH sessions, verify configuration on the machine that runs the server process. Desktop docs describe additional limits for Desktop-config servers during disconnected or certain Windows remote sessions.

A February 2026 issue reported that MCP configuration felt fragmented across CLI and Desktop. Treat it as one qualitative report, not a complete or current specification: Anthropic’s current documentation says local Desktop Code sessions can load multiple config sources and describes their precedence. The current official docs do not present a single cross-platform table of the Desktop file’s physical OS path; use the app’s documented setup/import flow instead of assuming a path from a different platform or install method.

How can I verify the setup safely?

Start with a harmless test server, use a unique name, and add it at only one scope. Confirm it with claude mcp list or /mcp, then test the intended surface. Before sharing .mcp.json, inspect the diff and remove credentials or machine-specific secrets; use documented environment-variable expansion or your organization’s approved secret storage. MCP connections grant access to external tools or data, so verify that you trust the server before approving it.

This is a documentation map, not a test of every Desktop version, operating system, or server. Anthropic docs and the linked issue were checked November 3, 2026. Related: troubleshoot Claude Code MCP connections behind a proxy and compare official MCP setup docs across coding clients.

Sources and scope limits

• Anthropic Claude Code MCP documentation covers scopes, precedence, list/status commands, and Desktop import.
• Anthropic Claude Code Desktop documentation describes shared configuration and how the Code tab loads Desktop, user, and project servers.
• Anthropic settings documentation explains ~/.claude.json and distinguishes it from settings JSON.
• Issue #27458 is one user report about configuration fragmentation, not a complete current specification.