services/mcp/ — Model Context Protocol Service

Contents

Architecture

flowchart TD
  CFG["config.ts\nMulti-scope Config Loader"] -->|server configs| CM["MCPConnectionManager.tsx"]
  CM -->|create connections| CL["client.ts\nMCP Client Factory"]
  CL -->|stdio| ST["Stdio Transport"]
  CL -->|sse/http| HT["SSE / HTTP Transport"]
  CL -->|websocket| WS["WebSocket Transport"]
  CL -->|sdk| SDK["InProcessTransport"]
  CL -->|claudeai-proxy| CAI["Claude.ai Proxy"]
  CL --> TD["Tool Discovery\nfetchToolsForClient()"]
  CL --> RD["Resource Discovery\nfetchResourcesForClient()"]
  CL --> CMD["Command Discovery\nfetchCommandsForClient()"]
  TD --> MCPTool["MCPTool extends Tool"]
  AUTH["auth.ts\nOAuth + XAA"] -->|tokens| CL
  EH["elicitationHandler.ts"] -->|user prompts| CL
  CP["channelPermissions.ts"] -->|permission relay| CL
  UTILS["utils.ts\nFiltering & Hashing"] --> CM

Connection Lifecycle

stateDiagram-v2
  [*] --> Pending : Config loaded
  Pending --> Connected : Transport established
  Pending --> NeedsAuth : OAuth required
  Pending --> Failed : Connection error
  NeedsAuth --> Connected : Token acquired
  NeedsAuth --> Failed : Auth rejected
  Connected --> Failed : Runtime crash
  Connected --> Disabled : User disabled
  Failed --> Pending : Reconnect attempt
  Disabled --> Pending : User re-enabled
  Connected --> [*] : Shutdown

Key Classes & Functions

Data Structures

Interactions

Configuration

Directory Map

mcp/
├── auth.ts                        ← OAuth + XAA authentication (2,139 lines)
├── channelAllowlist.ts            ← GrowthBook-backed channel allowlist
├── channelNotification.ts         ← Channel notification gating & wrapping
├── channelPermissions.ts          ← Permission relay over messaging channels
├── claudeai.ts                    ← Claude.ai org MCP server fetching
├── client.ts                      ← Primary MCP client & tool execution (2,750 lines)
├── config.ts                      ← Multi-scope config aggregation (1,700 lines)
├── elicitationHandler.ts          ← Form-based user prompt handling
├── envExpansion.ts                ← ${VAR} expansion in config values
├── headersHelper.ts               ← Dynamic header generation via scripts
├── InProcessTransport.ts          ← Linked in-process transport pair
├── MCPConnectionManager.tsx       ← React connection state manager
├── mcpStringUtils.ts              ← Tool name parsing (mcp__server__tool)
├── normalization.ts               ← Server name normalization
├── oauthPort.ts                   ← OAuth callback port management
├── officialRegistry.ts            ← Official MCP server registry
├── SdkControlTransport.ts         ← SDK ↔ CLI transport bridge
├── types.ts                       ← Core types & Zod schemas
├── useManageMCPConnections.ts     ← React hook for connection management
├── utils.ts                       ← Filtering, hashing, stale detection
├── vscodeSdkMcp.ts                ← VS Code SDK MCP integration
├── xaa.ts                         ← Cross-App Access token exchange
└── xaaIdpLogin.ts                 ← XAA identity provider login flow

Deep-Dive Highlights

Core mechanisms from this sub-module have been extracted into dedicated focus areas. Each topic covers one protocol, subsystem, or security mechanism in detail.

Deep-Dive Pages

Transport Comparison

Tool Naming Convention

MCP tools follow the triple-underscore naming pattern: mcp__<serverName>__<toolName>. The mcpStringUtils.ts module provides parsing and generation utilities:

import { mcpInfoFromString, buildMcpToolName, getMcpDisplayName } from './mcpStringUtils';

// Parse: "mcp__github__search_repos" → { server: "github", tool: "search_repos" }
const info = mcpInfoFromString('mcp__github__search_repos');

// Build: ("github", "search_repos") → "mcp__github__search_repos"
const fullName = buildMcpToolName('github', 'search_repos');

// Display: strip prefix for user-facing name
const display = getMcpDisplayName('mcp__github__search_repos', 'github');
// → "search_repos"

Code Examples

Example 1: Multi-Scope Config Aggregation

import { getAllMcpConfigs } from './config';

// Aggregates from all sources with precedence:
//   1. Enterprise managed-mcp.json (highest)
//   2. User ~/.claude/settings.json
//   3. Project .mcp.json
//   4. Plugin-provided servers (dynamic scope)
//   5. Claude.ai organization servers
const configs = await getAllMcpConfigs();

for (const [name, config] of Object.entries(configs)) {
  console.log(`${name} [${config.scope}]:`);
  if (config.type === 'stdio') {
    console.log(`  command: ${config.command} ${config.args?.join(' ')}`);
  } else if (config.type === 'sse' || config.type === 'http') {
    console.log(`  url: ${config.url}`);
    if (config.headersHelper) {
      console.log(`  headers via: ${config.headersHelper}`);
    }
  }
}

Example 2: MCP Tool Execution with OAuth Retry

import { MCPTool, createMcpClientConnection } from './client';
import { getMcpServerHeaders } from './headersHelper';

// Establish connection with transport auto-detection
const connection = await createMcpClientConnection(serverName, config);
if (connection.type !== 'connected') {
  throw new Error(`Connection failed: ${connection.type}`);
}

// Discover available tools
const tools = await fetchToolsForClient(connection.client);
const searchTool = tools.find(t => t.name === 'mcp__myserver__search');

// Execute with automatic OAuth 401 retry (max 2 attempts)
if (searchTool instanceof MCPTool) {
  const result = await searchTool.call(
    { query: 'find all TypeScript files' },
    { timeout: 30000 }
  );
  // Results are auto-truncated if too large
  console.log(result.content);
}

Example 3: Environment Variable Expansion in Config

import { expandEnvVarsInString } from './envExpansion';

// Supports ${VAR} and ${VAR:-fallback} syntax
const { expanded, missingVars } = expandEnvVarsInString(
  'https://${API_HOST:-localhost}:${API_PORT}/mcp'
);
// If API_HOST="prod.example.com" and API_PORT is unset:
//   expanded = "https://prod.example.com:${API_PORT}/mcp"
//   missingVars = ["API_PORT"]

if (missingVars.length > 0) {
  console.warn(`Missing env vars: ${missingVars.join(', ')}`);
}