MCP Server Discovery

• Entity ID: ent-20260410-a1a4325ff3b6
• Type: mechanism
• Scope: shared
• Status: active
• Aliases: MCP config, MCP server configuration, .mcp.json

Description

MCP server discovery (src/services/mcp/config.ts) loads server definitions from 7 configuration scopes, merges them with a defined precedence order, deduplicates across sources, enforces deny/allow policies, and provides the final server list for connection. It supports 8 server config types (stdio, SSE, SSE-IDE, HTTP, WebSocket, WS-IDE, SDK, and claude.ai proxy).

Configuration scopes

Servers are discovered from 7 scopes (later wins on name conflicts):

When enterprise config exists, it takes exclusive control — all other scopes are ignored.

Config file format

.mcp.json is validated against McpJsonConfigSchema:

{
  "mcpServers": {
    "server-name": {
      "type": "stdio",
      "command": "node",
      "args": ["server.js"],
      "env": { "KEY": "value" }
    }
  }
}

Written atomically: writeMcpjsonFile() uses temp file, datasync(), then rename(), preserving original file permissions.

Server config types

Deduplication strategies

Three strategies prevent duplicate registrations:

1. Plugin dedup (dedupPluginMcpServers) — matches by signature (stdio command array or URL). Manual config wins over plugin; first plugin wins ties.
2. Claude.ai dedup (dedupClaudeAiMcpServers) — only enabled manual servers count as dedup targets.
3. CCR proxy unwrap (unwrapCcrProxyUrl) — extracts the original vendor URL from CCR proxy path markers (/v2/session_ingress/shttp/mcp/, /v2/ccr-sessions/) so a proxied server and its direct URL are recognized as the same server.

Policy enforcement

• Deny list: isMcpServerDenied() checks deniedMcpServers in settings by name, command, or URL pattern. Supports wildcard * matching.
• Allow list: isMcpServerAllowedByPolicy() checks allowedMcpServers allowlist.
• Plugin-only mode: isRestrictedToPluginOnly('mcp') blocks all non-plugin servers.
• Enterprise managed: when managed-mcp.json exists at the enterprise managed path, it takes exclusive control of all MCP configuration.

Connection concurrency

getMcpToolsCommandsAndResources() splits servers into local (stdio/sdk) and remote groups, processing each with different concurrency limits via processBatched(). Local servers get lower concurrency (process spawning overhead); remote servers get higher concurrency (network I/O only).

Platform handling

Config validation detects Windows + npx command without cmd /c wrapper and emits a warning with a fix suggestion. This is a common gotcha on Windows where npx requires a shell wrapper.

Trade-offs

1. 7 scopes — very flexible for different deployment scenarios (personal, team, enterprise) but complex precedence. Enterprise override simplifies managed environments at the cost of user freedom.
2. Atomic writes — datasync() + rename() prevents corrupt .mcp.json but is slower than a direct write.
3. Approval required for project servers — .mcp.json servers only connect if marked approved, preventing untrusted repos from auto-connecting to arbitrary servers. Adds friction for legitimate use.
4. CCR proxy unwrap — deduplicates proxied servers correctly but depends on specific URL path patterns that could break if the proxy format changes.

Depends on

• config-schemas — Zod validation schemas for server configs
• permission-pipeline — deny/allow rule enforcement

Key claims

• Enterprise MCP config takes exclusive control, disabling all other config scopes
• Project-level .mcp.json servers require explicit approval before connecting
• Config files are written atomically (temp file + datasync + rename)
• Windows users are warned when using npx without cmd /c wrapper

Relations

• part_of mcp-subsystem
• depends_on config-schemas
• depends_on permission-pipeline

Sources

src-20260409-a5fc157bc756, source code analysis of src/services/mcp/config.ts