commands/mcp/ — MCP Server Management Commands

Contents

Architecture

flowchart TD
  USER["User CLI / UI"] -->|"/mcp add"| ADD["addCommand.ts"]
  USER -->|"/mcp enable/disable"| MCP["mcp.tsx"]
  USER -->|"/mcp xaa setup"| XAA["xaaIdpCommand.ts"]
  ADD -->|"addMcpConfig()"| CFG["services/mcp/config.ts"]
  ADD -->|"saveMcpClientSecret()"| AUTH["services/mcp/auth.ts"]
  MCP -->|"useMcpToggleEnabled()"| MGR["MCPConnectionManager.tsx"]
  MGR -->|"useManageMCPConnections()"| STATE["AppState.mcp.clients"]
  XAA -->|"acquireIdpIdToken()"| IDP["services/mcp/xaaIdpLogin.ts"]
  IDP -->|"OIDC flow"| BROWSER["Browser Auth"]
  CFG -->|"read/write"| FILES["Config Files"]
  AUTH -->|"store secrets"| KEYCHAIN["Secure Keychain"]

Command Routing

flowchart LR
  CMD["/mcp args"] --> PARSE{"Parse args[0]"}
  PARSE -->|"no args"| UI["MCPSettings Panel"]
  PARSE -->|"enable"| TOG["MCPToggle Component"]
  PARSE -->|"disable"| TOG
  PARSE -->|"reconnect"| REC["MCPReconnect Component"]
  PARSE -->|"no-redirect"| PLG["PluginSettings Panel"]
  TOG -->|"target=all"| ALL["Toggle All Servers"]
  TOG -->|"target=name"| ONE["Toggle Single Server"]
  ALL --> HOOK["useMcpToggleEnabled()"]
  ONE --> HOOK

Key Classes & Functions

Data Structures

Interactions

Configuration

Directory Map

mcp/
├── index.ts              ← Command registration metadata (type, name, aliases, lazy load)
├── mcp.tsx               ← UI /mcp command: enable/disable/reconnect/settings routing
├── addCommand.ts         ← CLI "claude mcp add" subcommand (server registration)
└── xaaIdpCommand.ts      ← CLI "claude mcp xaa" subcommands (setup/login/show/clear)

Deep-Dive Highlights

Core mechanisms from this sub-module have been extracted into dedicated focus areas for in-depth exploration. Each section covers a key protocol, flow, or subsystem.

Code Examples

Example 1: Registering an MCP Server via CLI

// addCommand.ts — action handler (simplified)
async function action(
  name: string,
  commandOrUrl: string,
  extraArgs: string[],
  options: AddOptions
): Promise<void> {
  const scope = ensureConfigScope(options.scope)
  const transport = ensureTransport(options.transport)

  // Validate server name: alphanumeric, hyphens, underscores only
  if (!/^[a-zA-Z0-9_-]+$/.test(name)) {
    cliError('Server name can only contain letters, numbers, hyphens, and underscores')
    process.exit(1)
  }

  if (transport === 'http' || transport === 'sse') {
    const headers = options.header ? parseHeaders(options.header) : undefined
    const oauth: McpOAuthConfig | undefined = options.clientId
      ? { clientId: options.clientId, callbackPort: options.callbackPort, xaa: options.xaa }
      : undefined

    await addMcpConfig(name, { type: transport, url: commandOrUrl, headers, oauth }, scope)

    if (options.clientSecret) {
      const secret = await readClientSecret()
      saveMcpClientSecret(name, { type: transport, url: commandOrUrl, oauth }, secret)
    }
  } else {
    const env = options.env ? parseEnvVars(options.env) : undefined
    await addMcpConfig(name, { type: 'stdio', command: commandOrUrl, args: extraArgs, env }, scope)
  }

  logEvent('tengu_mcp_add', { type: transport, scope, source: 'command' })
  cliOk(`Added ${name} to ${describeMcpConfigFilePath(scope)}`)
}

Example 2: Toggling MCP Servers in the UI

// mcp.tsx — MCPToggle component
function MCPToggle({
  action,
  target,
  onComplete,
}: {
  action: 'enable' | 'disable'
  target: string
  onComplete: (result: string) => void
}): null {
  const clients = useAppState(s => s.mcp.clients)
  const toggleMcpServer = useMcpToggleEnabled()
  const hasRun = useRef(false)

  useEffect(() => {
    if (hasRun.current) return
    hasRun.current = true

    const enable = action === 'enable'
    const filtered = clients.filter(c => c.name !== 'ide')

    if (target === 'all') {
      const toToggle = filtered.filter(c =>
        enable ? c.type === 'disabled' : c.type !== 'disabled'
      )
      toToggle.forEach(c => toggleMcpServer(c.name, enable))
      onComplete(`${enable ? 'Enabled' : 'Disabled'} ${toToggle.length} servers`)
    } else {
      const server = filtered.find(c => c.name === target)
      if (!server) { onComplete(`Server "${target}" not found`); return }
      toggleMcpServer(server.name, enable)
      onComplete(`${enable ? 'Enabled' : 'Disabled'} ${server.name}`)
    }
  }, [])

  return null
}

Example 3: XAA IdP Setup

// xaaIdpCommand.ts — setup action (simplified)
async function setupAction(options: {
  issuer: string
  clientId: string
  clientSecret?: boolean
  callbackPort?: number
}): Promise<void> {
  // Validate issuer URL (must be https, except loopback)
  const url = new URL(options.issuer)
  const isLoopback = ['localhost', '127.0.0.1', '[::1]'].includes(url.hostname)
  if (url.protocol !== 'https:' && !isLoopback) {
    cliError('Issuer must use https:// (except loopback addresses)')
    process.exit(1)
  }

  // Save non-secret config to settings
  const settings: XaaIdpSettings = {
    issuer: options.issuer,
    clientId: options.clientId,
    callbackPort: options.callbackPort,
  }
  updateSettingsForSource('userSettings', { xaaIdp: settings })

  // Store client secret in keychain if provided
  if (options.clientSecret) {
    const secret = process.env.MCP_XAA_IDP_CLIENT_SECRET
    if (!secret) {
      cliError('Set MCP_XAA_IDP_CLIENT_SECRET env var when using --client-secret')
      process.exit(1)
    }
    saveIdpClientSecret(issuerKey(options.issuer), secret)
  }

  cliOk(`XAA IdP connection configured for ${options.issuer}`)
}