AnthropicClaude Certified Architect – Foundations2026-102.4 Integrate MCP servers into Claude Code and agent workflows
Combine server capabilities without assuming readiness
Completed by the knowledge check
Learning objective
Explain how connecting multiple MCP servers exposes their available tools in one agent workflow.
Core idea
Several MCP servers can contribute tools to one Claude Code or Agent SDK workflow. A code-review agent can inspect repository issues, query documentation, and retrieve a database schema without running a separate agent for every integration. Each server contributes its own capability contract; the host makes those capabilities reachable within the same conversation.
Do not collapse configured, discovered, loaded, and permitted into one state. A configured server can fail to authenticate. A discovered tool can remain deferred until tool search loads its definition. A visible tool can still require permission. Multi-server integration succeeds when the workflow can obtain the needed capability from the intended server, not merely when several entries exist in a JSON file.
Scope and credentials are covered in 2.4.1 and 2.4.2. Here the architectural question is what the agent can actually reach during a turn.
How it works
Discover capabilities by server
MCP clients discover tools with tools/list and invoke them with tools/call. In protocol revision 2026-07-28, a server declaring the tools capability must return the tools available to the requesting client. The set can be empty and can depend on the authorization presented with the request. A server catalog is therefore not a promise that every authenticated account receives every advertised operation.
Claude Code sends capability discovery requests after a server connects. Its host-level tool naming keeps server identity visible. In the Agent SDK, mcp__<server-name>__<tool-name> identifies a tool: a list_issues tool on the github server becomes mcp__github__list_issues. Tools from another server remain separately named even if their server-side operation names resemble each other.
Distinct names let one workflow call several integrations, but they do not make overlapping descriptions unambiguous. See 2.4.4 for describing the evidence each capability provides. A namespace identifies the source; a description explains when that source is appropriate.
Separate discovery from schema loading
Claude Code enables MCP tool search by default. It loads tool names and server instructions at session start and defers tool definitions until Claude needs them. Claude uses ToolSearch to discover the relevant definitions and then calls the selected tools. This preserves context when many servers expose large menus.
ENABLE_TOOL_SEARCH=false loads all MCP tools upfront. ENABLE_TOOL_SEARCH=auto uses threshold mode: definitions load upfront while their total is below 10% of the context window, and are deferred when they reach that threshold. auto:N selects a percentage from 0 to 100. These are explicit modes; the unset default is on-demand deferral, not the 10% threshold mode.
For a small server needed on every turn, its configuration can set alwaysLoad: true to exempt its tools from deferral. That increases upfront context usage. It is a loading choice, not authorization to run those tools. Avoid switching the entire workflow to upfront loading merely to compensate for an unclear server instruction.
Tool search requires support for tool_reference blocks. Anthropic documents support for Claude Sonnet 4.5, Haiku 4.5, Opus 4.5, and later models. Microsoft Foundry deployments hosted on Azure reject tool search server-side, so Claude Code loads tools upfront there. Google Cloud’s Agent Platform models earlier than that generation also use upfront loading. A non-first-party ANTHROPIC_BASE_URL disables search by default; an explicit override can fail if the proxy does not support the required blocks. CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS keeps search off and cannot be overridden with ENABLE_TOOL_SEARCH.
These boundaries describe Claude Code’s integration behavior. Do not infer that a particular search setting changes the MCP protocol’s discovery contract or grants a server additional operations.
Observe readiness in the Agent SDK
Configure direct server entries through TypeScript mcpServers or Python mcp_servers. At the start of a query, the SDK emits a system message with subtype init. Its tools array exposes the tool names known at that point, and mcp_servers reports server status. Status values include pending, connected, failed, needs-auth, and disabled.
A pending entry is not automatically a failed integration. It can still be connecting, or its cached tool list can be available while the actual connection waits until first use. The tools array can contain cached tools, connected tools, and omit tools from servers that have not supplied a list. Read the status and inventory together rather than treating the init message as an unconditional readiness barrier.
For directly configured stdio or uncached HTTP/SSE servers, the documented first-turn wait uses MCP_TIMEOUT, with a 30-second default. Settings-file servers can keep connecting in the background according to the host’s connection rules. With tool search enabled, Claude Code can tell Claude about tool names from servers that finish connecting during the turn, on its next request.
Permission remains separate. TypeScript allowedTools and Python allowed_tools pre-approve named MCP calls; they do not restrict the tool inventory to those names. If a server cannot connect, broadening an allow list does not supply missing credentials or tools. See 0.6 for the permission distinction.
Key distinctions and trade-offs
Use these states to interpret a multi-server workflow:
| State | Evidence | What it does not establish |
|---|---|---|
| Configured | Entry in mcpServers or .mcp.json | Connection succeeded |
| Discovered | Tool appears in a server or init inventory | Full definition is in model context |
| Loaded | Definition is available after search or upfront loading | Execution is pre-approved |
| Permitted | Applicable permission decision | Server-side authorization or availability |
Deferral reduces context consumption but adds a discovery step. Upfront loading can fit a small fixed menu but spends context on tools a turn never uses. Several connected servers provide complementary operations; they do not require that every operation execute simultaneously.
Architecture / decision scenario
A developer productivity agent uses issue, documentation, and schema servers in one investigation. It needs issue evidence, the documented behavior, and the affected schema before proposing a patch.
The host configures all three servers and inspects the SDK init inventory. The issue server is connected, the documentation server contributes cached tools while pending, and the schema server reports needs-auth. The agent can search for the first two integrations’ relevant capabilities. The host repairs schema authentication rather than claiming that the presence of its configuration supplies schema evidence.
The workflow retains tool search instead of loading every server definition upfront. It gives each server instructions that identify its evidence category and pre-approves only the calls the application intends to run without prompts. The final answer identifies the schema gap until the schema operation succeeds; it does not substitute local text search for missing remote evidence.
Common exam traps
- Equating a configured server with a connected and authorized server.
- Designing a separate agent or a mode switch per server when one workflow can reach them all.
- Assuming every tool definition is loaded at connection time.
- Treating
pendingas proof that no cached tools are available. - Confusing
allowedToolswith a tool exposure restriction. - Assuming a
needs-authorfailedserver supplies usable tools.
Where the exam guide differs
The exam guide says tools from all configured servers are “discovered at connection time and available simultaneously.” Read that as the combined capability set for one workflow, not a guarantee of immediate schema loading or readiness. Claude Code documents default on-demand tool search, background connection, and SDK inventories that depend on connection or cached discovery. In an exam item, distinguish the intended multi-server access from the stronger claim that every configured tool is usable immediately.
The exam guide (version 1.0, effective July 2026, first drafted in February 2026) names no MCP revision; it was written while revision 2025-11-25 was the published specification. This lesson cites revision 2026-07-28, a later revision, and the differences between the two do not change what it teaches for the exam. Revision 2026-07-28 removes the initialize handshake: each request carries its protocol version and client capabilities in _meta, and servers must implement server/discover to advertise their versions, capabilities, and identity. Tool discovery through tools/list and invocation through tools/call work the same way in both revisions.
What to remember
Several servers can support one conversation, with names that preserve their origin. Verify discovery and connection evidence, load definitions through the supported search path, and apply permission separately. A combined tool set is useful only when the needed server and capability are actually available.
Knowledge check
An Agent SDK investigation needs evidence from an issue server, a documentation server and a schema server. The init message reports the issue server connected, the documentation server pending with cached tools, and the schema server needs-auth. The answer must cite the affected schema. What should the host do?
mcp__schema__* to allowedTools before the next queryENABLE_TOOL_SEARCH=false before the next queryneeds-auth server is configured but supplies no usable tools until it is authorized, so the schema evidence is missing for a credential reason. An allow-list entry only pre-approves calls and loading definitions upfront changes context use; neither supplies credentials. A pending server can still offer cached tools, and waiting for it does nothing for the schema gap.An Agent SDK application connects issue, documentation and schema servers and sets allowedTools: ["mcp__issues__search"], expecting Claude to use only that tool. Logs show Claude requesting mcp__docs__fetch_page. Why?
allowedTools , which matches only wildcard patternsallowedTools pre-approves the tools it lists; unlisted tools stay availableallowedTools was appliedallowedTools adds allow rules: listed calls run without a permission prompt, while every other tool stays available and its calls fall through to the permission mode. It is approval, not a restriction on the inventory. Exact names such as mcp__db__query are valid entries beside wildcards.A Claude Code workflow connects five large MCP servers and one small ticket-context server whose two tools Claude needs on every turn. Claude takes a tool search step before each ticket-context call. Which change removes that step for those two tools while keeping the other servers deferred?
alwaysLoad: true in the ticket-context server’s configuration entryENABLE_TOOL_SEARCH=false in the environment for the whole sessionENABLE_TOOL_SEARCH=auto in the environment for the whole sessionticket-context tools to the session’s allowed tools listalwaysLoad: true exempts one server’s tools from deferral and leaves the rest searchable. Turning tool search off loads every server upfront, auto loads everything upfront only while all definitions fit under 10% of the context window, and an allow list approves calls without changing how definitions load.A code-review agent needs open issue discussions, the documented API behaviour and the current database schema to propose one fix. Three MCP servers provide these. The team wants the least coordination overhead. Which design fits?
mcp__<server-name>__<tool-name> naming keeps each tool’s origin distinct, so one agent can gather all three kinds of evidence. Per-server agents and mode switches add coordination the task does not need, and collapsing the servers under one name hides the source that the namespace exists to show.References
- Anthropic, Connect Claude Code to tools via MCP
- Anthropic, Connect to external tools with MCP
- Model Context Protocol, Tools, protocol revision 2026-07-28
- Anthropic, Claude Certified Architect – Foundations Exam Guide
- Model Context Protocol, Key Changes, protocol revision 2026-07-28