InkdownInkdown
Start writing

Claude-Code

62 filesยท4 subfolders

Shared Workspace

Claude-Code
codex

0700_mcp_integration_connection_and_tool_call_flow

Shared from "Claude-Code" on Inkdown

Critical Flow: MCP Server Connection, Tool Call, And Result Handling

MCP is one of the most dynamic parts of the client. A junior engineer should understand both how server configs are assembled and how an MCP tool call becomes a model-visible result.

Flow Overview

  1. Gather config from all MCP sources.
  2. Filter and deduplicate config.
  3. Connect transports and discover tools, resources, and prompts.
  4. Expose MCP tools, commands, and resources to the model and UI.
  5. Execute MCP tool calls, including auth, elicitation, and large-result handling.

Every Hop

1. Config assembly

services/mcp/config.ts merges MCP config from:

  • --mcp-config CLI input.
0000_start_here_index_and_recommended_reading_order.md
0100_project_overview_tech_stack_runtime_modes_and_folder_map.md
0200_startup_flow_entry_points_and_cold_start_sequence.md
0300_codebase_modules_layers_state_models_and_schemas.md
0400_system_architecture_and_design_rationale.md
0500_interactive_repl_request_flow_end_to_end.md
0600_headless_sdk_and_print_mode_request_flow_end_to_end.md
0700_mcp_integration_connection_and_tool_call_flow.md
0800_external_services_sdks_storage_and_local_dependencies.md
0900_environment_variables_settings_feature_flags_and_failure_modes.md
1000_non_obvious_patterns_gotchas_and_debugging_traps.md
1100_full_codebase_file_inventory_grouped_by_directory.md
kimi
00-overview.md
01-entrypoints.md
02-state-management.md
03-query-system.md
04-tools-system.md
05-tasks-system.md
06-ui-components.md
07-bridge-remote.md
08-services.md
09-skills-plugins.md
10-commands.md
11-testing-architecture.md
12-permission-system.md
13-build-system.md
14-ink-internals.md
15-git-internals.md
16-context-compaction.md
17-vim-mode.md
18-mailbox-notifications.md
19-session-persistence.md
20-hooks-system.md
21-error-recovery.md
README.md
qwen
00-overview.md
01-entry-points.md
02-query-engine.md
03-tools-and-tasks.md
04-commands-and-skills.md
05-state-management.md
06-ink-rendering.md
07-bridge-remote.md
08-mcp-services.md
09-services-overview.md
10-multi-agent.md
11-system-prompt-constants.md
12-tool-interface.md
13-memory-system.md
14-buddy-companion.md
15-keybindings.md
16-stop-hooks.md
17-vim-mode.md
18-upstreamproxy.md
19-cost-tracking-history.md
20-contexts-styles-onboarding.md
21-hooks.md
22-screens.md
tweets-explain
claude-code-memory-analysis.md
compact
memory-system
agentic-architecture
  • User, project, local, and flag settings.
  • .mcp.json.
  • Plugin-provided MCP servers.
  • Enterprise or managed restrictions.
  • Claude.ai connector discovery.

    • Important details:

    • Every server gets a scope such as local, user, project, dynamic, enterprise, claudeai, or managed.
    • Dedup is content-based using server signatures, not just names.
    • Plugin servers can be suppressed if they duplicate manually configured or Claude.ai-derived servers.
    2. Config reaches startup
    • main.tsx loads local MCP configs early so file I/O overlaps with setup work.
    • In interactive mode, actual connections are delayed until after trust because connecting a server can execute code.
    • In headless mode, MCP connection is awaited or pushed into the headless store so the first turn can use discovered tools.
    3. Client connection logic

    services/mcp/client.ts owns transport and lifecycle details:

    • stdio via StdioClientTransport.
    • sse via SSEClientTransport.
    • http via StreamableHTTPClientTransport.
    • ws via a custom WebSocketTransport.
    • sdk via SdkControlClientTransport.
    • It also owns OAuth refresh, Claude.ai connector auth, XAA support, session-expired detection, proxy and mTLS plumbing, reconnect behavior, tool and resource discovery, large-result truncation, and binary persistence helpers.
    4. MCP state is added to the client
    • Connected clients, tools, commands, and server resources are stored under AppState.mcp.
    • Tool wrappers such as MCPTool, ListMcpResourcesTool, ReadMcpResourceTool, and McpAuthTool are added to the tool pool.
    • The UI surfaces connection state through settings panels, dialogs, and status notifications.
    5. Model emits an MCP tool call
    • From the model perspective, MCP tools are just tools in the same tool list.
    • When toolExecution.ts resolves a tool name and finds an MCP-backed tool, the call is routed through the MCP client layer.
    6. Auth and elicitation handling
    • The MCP server can require auth, producing needs-auth state.
    • The server can emit URL elicitation requirements routed through services/mcp/elicitationHandler.ts.
    • Session expiry or transport reconnect handling can clear or refresh the cached connection.
    7. Result shaping and persistence
    • Large or binary outputs can be persisted through utils/mcpOutputStorage.ts.
    • Result content is validated and truncated by utils/mcpValidation.ts.
    • Tool results still flow back into the conversation through the same tool-result machinery as local tools.

    Why MCP Is Wired This Way

    • It keeps external tools inside the same model-facing abstraction as built-in tools.
    • It lets the client unify permissions, hooks, telemetry, and conversation history regardless of whether the action happened locally or through an external MCP server.
    • It gives enterprise policy a single choke point for allow, deny, and dedup behavior.

    Common MCP Debugging Questions

    • Why is my server missing? Check config scope, enterprise filtering, plugin dedup, and whether the server is disabled.
    • Why is it present but unusable? Check whether the client is pending, needs-auth, or failed.
    • Why does the model not see the tool on turn 1? Check whether the session is interactive or headless and whether trust or connection timing delayed discovery.
    • Why did the tool result go to a file? Large and binary output persistence is intentional.