The API MCP Connector: mcp_toolset, defer_loading, and enabled
AdvancedUnderstand MCP servers, their primitives, and transports · Difficulty 3/5
Explanation
A Different Note Than "Transports in General"
The previous concept covers *which* transport an MCP Server uses. This concept is about a specific API-level mechanism for attaching a remote server directly to a Messages API request -- the API MCP Connector -- and the two per-tool controls it exposes once a server is attached.
Attaching a Server via mcp_toolset
The API MCP Connector lets you attach a remote MCP Server directly through the Messages API, without standing up your own MCP client. You do this with an mcp_toolset object placed in the request's tools array. That object carries a default_config block (settings applied to every tool on the server unless overridden) plus an optional configs object, keyed by individual tool name, for per-tool overrides.
Two Per-Tool Controls That Solve Different Problems
Both controls are booleans that live at the per-tool level, and it's easy to conflate them -- but they govern two entirely different concerns:
| Control | What it governs | Category |
|---|---|---|
defer_loading | Delays loading a tool's definition into context until the model actually needs it | Context-cost / scope mechanism |
enabled | Turns an individual tool fully on or off | Governance mechanism |
defer_loading is about *when* a tool's schema enters context -- set it to keep an upfront-heavy tool list from consuming context budget before the model has any reason to reach for it. enabled is about *whether* a tool is available to the model at all -- set it to false to register a server's connection but expose only a curated subset of its tools, regardless of context cost. A tool can be enabled: true and still have defer_loading: true (available, but not loaded into context until needed); the two settings are independent, and conflating "reduce context cost" with "restrict what the model can do" is exactly the trap this concept exists to prevent.
The Required Beta Header
Using the API MCP Connector -- the mcp_toolset object, default_config, and configs -- requires the mcp-client-2025-11-20 beta header on the request. Without it, the connector configuration does not take effect as described.
A Hard Limit: Remote Servers Only
The API MCP Connector supports only remote (HTTP-based) MCP servers. It does not support local stdio servers. If the MCP Server you need runs as a local subprocess (stdio), the API Connector cannot reach it -- you need a client that manages that connection directly, such as Claude Desktop or Claude Code, or a self-managed MCP client connection built with an SDK.
Common exam traps
- Confusing
defer_loadingwithenabled.defer_loadingdelays *when* a schema loads into context (a cost/scope lever);enableddecides *whether* the model can see the tool at all (a governance lever). A question describing "reduce context cost from a large tool list" points todefer_loading; a question describing "expose only these specific tools from a connected server" points toenabled. - Assuming the API MCP Connector can reach a local stdio server. It can't -- it supports remote/HTTP servers only; stdio requires Claude Desktop, Claude Code, or a self-managed SDK-based MCP Client connection.
- Forgetting the
mcp-client-2025-11-20beta header. Without it, themcp_toolsetconfiguration doesn't apply.
Key Takeaways
- The API MCP Connector attaches a remote MCP server directly via the Messages API using an mcp_toolset object in the tools array, with a default_config block plus optional per-tool configs keyed by tool name
- defer_loading (boolean) delays loading a tool's definition into context until the model needs it -- a context-cost/scope mechanism
- enabled (boolean) turns an individual tool fully on or off -- a governance mechanism, independent of defer_loading
- Using the connector requires the mcp-client-2025-11-20 beta header
- The API MCP Connector supports ONLY remote/HTTP MCP servers -- local stdio servers require Claude Desktop, Claude Code, or a self-managed MCP client connection via the SDK
Glossary Terms
An open standard protocol for connecting Claude to external tools and data sources. Defines a client-server architecture where MCP servers expose capabilities that MCP clients discover and use. Supports project-scoped (.mcp.json) and user-scoped configurations.
A process that implements the MCP protocol and exposes tools, resources, and prompts to MCP clients. Built with official SDKs (Python, TypeScript). Deployed locally via stdio or remotely via StreamableHTTP. Claude Code auto-discovers servers configured in .mcp.json.
An application that connects to MCP servers to access their tools, resources, and prompts. Responsible for tool-list filtering, tool_use_id routing, and enforcing which capabilities the model can call. Claude Code is the canonical MCP client in the CCA-F curriculum.
An MCP transport that communicates over HTTP with Server-Sent Events (SSE) for streaming. Runs as an independent network service — not a subprocess. Enables multiple simultaneous clients, per-request authentication, and remote deployment. The correct transport for shared, cloud-hosted, or containerised MCP servers.
An MCP transport mechanism where the client launches the server as a subprocess and communicates via stdin/stdout pipes. Ideal for local development and trusted single-user environments. Simple to set up but limited to same-machine deployment.
Related Concepts
MCP Transports: stdio vs. Streamable HTTP/Sockets
stdio: local subprocess transport, ideal for local, single-user integrations
MCP Configuration Scope (Four Levels) and the Secrets-in-Config Anti-Pattern
MCP configuration has four scope levels: Local (~/.claude.json, per-project, not shared), User (personal, across all projects, not shared), Project (.mcp.json at repo root, committed, shared with clones), and Enterprise (admin-managed, org-wide)