Claude Code MCP Assembly: Seven Config Sources, Three Capability Surfaces

When people talk about MCP, they often describe it as if it were just a way to expose remote tools.

That is not what Claude Code is doing. MCP is a capability import layer — config merging matters as much as transport, and external servers get adapted into Claude Code's native runtime objects.

File structure

src/
├── services/
│   ├── mcp/
│   │   ├── config.ts
│   │   ├── client.ts
│   │   ├── ChromeMcpClient.ts
│   │   └── types.ts

The core idea

Claude Code does not import MCP in one step.

It uses a staged assembly pipeline:

1. load server definitions from multiple scopes
2. apply precedence, approval, and policy rules
3. deduplicate configs that would hit the same underlying server
4. connect with transport-specific logic
5. discover tools, prompts, skills, and resources
6. wrap them into Claude Code's own runtime contracts

That means the real unit here is not "MCP connection."

It is capability assembly.

Why config.ts matters more than it first looks

If you only look at client.ts, you might think MCP is mostly about transport.

But config.ts is where the real product policy lives.

It decides:

• which scopes are allowed
• which project servers are approved
• whether enterprise config is exclusive
• whether MCP is locked to plugin-only
• whether plugin servers should be suppressed as duplicates
• whether claude.ai connectors should be suppressed as duplicates

Only after that does the runtime even attempt to connect.

That is good architecture. It keeps policy and transport from bleeding into each other.

Fast config path versus slow connector path

One of the cleaner choices here is that Claude Code distinguishes:

• a fast local config path
• a slower connector-aware path

getClaudeCodeMcpConfigs() stays mostly local and cheap.

getAllMcpConfigs() is the broader path that also waits for claude.ai connector discovery and then merges the result.

That split is useful because startup does not always want the full network-backed picture.

Sometimes it only needs the local, policy-vetted baseline first.

Why deduplication is based on server identity, not key names

The most practical detail in this subsystem is getMcpServerSignature().

Claude Code does not assume duplicate servers will share the same map key.

Instead it derives a signature from:

• stdio command plus args
• or normalized URL

That catches the real-world duplicate cases that matter:

• plugin server and manual server launching the same process
• rewritten proxy URL and raw vendor URL that actually point at the same backend

This is one of those small implementation details that reveals product maturity.

client.ts imports MCP into the native runtime vocabulary

The other major lesson is that Claude Code does not surface raw MCP SDK objects upward.

It wraps them into its own concepts.

For example, fetchToolsForClient() turns MCP tools into Claude Code Tool objects with:

• normalized tool names
• read-only and destructive hints
• permission integration
• classifier input support
• tool-call progress handling
• retry and auth recovery hooks

That is what makes an external capability feel native to the runtime.

MCP expands three surfaces, not one

Claude Code is also broader than the usual "MCP means more tools" framing.

A connected server can produce:

1. tools for the model
2. prompts that behave like command-like entrypoints
3. resources that can be listed and read through shared MCP resource tools

That is a better way to think about the system:

• MCP is not just remote execution
• it is a structured capability source

The real lesson

Claude Code does not treat MCP as a thin connector plugin.

It treats it as a capability assembly subsystem that turns external definitions into governed, native runtime surface.

That is why services/mcp/** belongs near the core of the architecture, not off to the side as "integration code."

// --- config.ts: policy layer (cheap, local-first) ---

// Fast path: returns locally-available configs only
async function getClaudeCodeMcpConfigs(cwd: string): Promise<McpServerConfig[]> {
const [enterprise, plugin, user, project, local, dynamic] = await Promise.all([
  getEnterpriseMcpConfigs(),
  getPluginMcpConfigs(),
  getUserMcpConfigs(),
  getProjectMcpConfigs(cwd),
  getLocalMcpConfigs(cwd),
  getDynamicMcpConfigs(),
])

return dedupAndFilter([enterprise, plugin, user, project, local, dynamic])
}

// Identity-based dedup — two configs are the same server if they produce the same signature
function getMcpServerSignature(config: McpServerConfig): string {
if (config.type === 'stdio') {
  return `stdio:${config.command} ${config.args?.join(' ')}`
}
return `url:${normalizeUrl(config.url)}`
}

// --- client.ts: connection + discovery + adaptation ---

async function getMcpToolsCommandsAndResources(
configs: McpServerConfig[],
context: ToolUseContext,
): Promise<{ tools: Tool[]; commands: Command[]; resources: ServerResource[] }> {
const clients = await Promise.all(configs.map(cfg => connectToServer(cfg, context)))
const connected = clients.filter(c => c.type === 'connected')

const [tools, commands, resources] = await Promise.all([
  Promise.all(connected.map(c => fetchToolsForClient(c, context))),
  Promise.all(connected.map(c => fetchCommandsForClient(c, context))),
  Promise.all(connected.map(c => fetchResourcesForClient(c, context))),
])

return {
  tools: tools.flat().map(wrapMcpTool),         // MCP tool → Claude Code Tool
  commands: commands.flat().map(wrapMcpCommand), // MCP prompt → Command
  resources: resources.flat(),
}
}