Sókrates Wiki

MCP Server Precedence and Hosted Connectors

3 min read

MCP Server Precedence and Hosted Connectors

Summary

This law defines the priority logic used by Claude Code to resolve Model Context Protocol (MCP) server definitions. It establishes that local configuration files always take precedence over hosted Claude.ai connectors, requiring the removal of local stubs to enable cloud-based integrations like Gmail.

Details

The Model Context Protocol (MCP) is the standard through which the Claude Code CLI interacts with external tools and data sources. Within the Sokrates development environment, a critical architectural constraint governs how these servers are initialized: Local configuration takes precedence over hosted connectors.

The Precedence Rule

When the Claude Code environment initializes, it aggregates MCP server definitions from three primary levels:

  1. Global Configuration: Located at ~/.claude.json.
  2. Project/Plugin Configuration: Located in .mcp.json files within specific directory roots (e.g., /plugins/ai-sentinel/.mcp.json).
  3. Hosted Connectors: Configured via the Claude.ai web interface at claude.ai/settings/connectors.

If a server identifier (such as gmail) is defined in a local JSON file, Claude Code attempts to initialize it as a local stdio process. If a local entry exists, the CLI will explicitly skip the corresponding hosted connector provided by the Claude.ai account. This “shadowing” occurs even if the local configuration is invalid or points to a non-existent package.

Hosted vs. Local Servers

A common point of failure in the Sokrates stack involved attempts to configure Gmail as a local MCP server. Investigation revealed that there is no public @anthropic/mcp-gmail npm package for local execution. Instead, Gmail functionality is provided as a Hosted OAuth Connector.

Unlike local servers that run via npx or direct binary execution, hosted connectors flow through the user’s authenticated Claude.ai session. They are managed via Google OAuth on the Anthropic web platform and do not require any entries in the mcpServers section of local configuration files.

Configuration and Troubleshooting

To successfully integrate hosted services like Gmail into the CLI, the following state must be maintained:

  • Web Authentication: The connector must be enabled and authenticated at https://claude.ai/settings/connectors.
  • Local Deletion: Any gmail keys must be removed from the mcpServers object in ~/.claude.json and any local .mcp.json files.
  • Registry Synchronization: Claude Code synchronizes these connectors upon login. The presence of a service in the claudeAiMcpEverConnected list in the config file indicates the CLI is aware of the hosted option, but it will only activate if no local name-collision exists.

Symptoms of Violation

When this precedence law is violated (e.g., a “bogus” local entry exists for a hosted service), the CLI typically reports:

  • Failed to reconnect to [service name]
  • Errors indicating that a package (like @anthropic/mcp-gmail) cannot be found in the npm registry.
  • The /mcp command showing the server in a failed state despite it being active on the web interface.

In the Sokrates project, this was specifically observed when the ai-sentinel plugin and the residual-modeling project both contained redundant or incorrect MCP definitions that blocked the primary Gmail connector.

Graph View

Backlinks