The Claude Agent SDK and Model Context Protocol (MCP)

The Agent SDK packages Claude Code's own agent loop so you can embed it in your own applications, and MCP standardizes how that loop — or any AI application — connects to the outside world. One gives Claude a way to keep acting; the other gives it a common plug for everything it might act on.

The agent loop, underneath everything

☺ Like you're 10: It's like doing homework — read the question, try a step, check it, then look at the next question — except Claude keeps going until there's nothing left to check.

Every module up to this point has really been building toward the same cycle. The Claude Agent SDK lets you "embed Claude Code's autonomous agent loop in your own applications" without needing the Claude Code CLI itself, and it describes that loop in five steps: receive a prompt, Claude evaluates it and responds with text and/or tool calls, the SDK executes those tools and feeds the results back automatically, this repeats — each cycle is one "turn" — until Claude produces output with no tool calls, and finally the SDK returns a result.

This is the same shape Claude Code's own documentation describes more informally as three blended, repeating phases: gather context, take action, verify work — where verification leans on deterministic signals like linters, type checkers, tests, and runtime errors, not just the model's own judgment. If you've been hand-rolling a tool_use / tool_result loop against the raw Messages API, this is that same loop. It's just been given a name and a lot of supporting infrastructure.

What the SDK gives you on top of the raw loop

A hand-written tool-use loop gets you the mechanics: send tools, read back tool_use blocks, execute them, send tool_result blocks, repeat. The Agent SDK ships the same built-in tools Claude Code uses — file tools like Read/Edit/Write, search tools like Glob/Grep, Bash, WebSearch/WebFetch, ToolSearch, and orchestration tools like Agent/Skill/AskUserQuestion/TaskCreate/TaskUpdate — plus the surrounding controls that make a loop safe and steerable enough to run unattended:

• Tool access controls — allowed_tools / disallowed_tools to scope exactly which capabilities an agent run can use.
• Permission modes — a spectrum from default (reads only, everything else prompts) through acceptEdits, plan, auto, dontAsk, up to bypassPermissions for isolated sandboxes.
• Budget caps — max_turns and max_budget_usd to bound how long or how expensive a single run can get.
• Effort levels — low/medium/high/xhigh/max, controlling how much the model reasons before acting.
• Context and session management — automatic context compaction as a session grows, plus a session_id returned with the final result so a run can be resumed later.
• Hooks and subagents — lifecycle hooks (PreToolUse, PostToolUse, UserPromptSubmit, Stop, and more) for deterministic control at specific points in the loop, and subagents for offloading context-heavy subtasks into their own context window.
• MCP support — the SDK can connect to MCP servers and register custom tool handlers alongside its built-in tools, which is the bridge into the rest of this page.

The problem MCP solves

☺ Like you're 10: Before MCP, hooking Claude up to Slack, and hooking some other assistant up to Slack, meant building the "talk to Slack" adapter twice — with slightly different wiring each time.

Once an agent has a loop, it needs things to act on: your ticketing system, your codebase, your internal docs, a calendar, a CRM. Historically, every pairing of AI application and data source has meant custom, non-reusable integration code — the auth handling, error handling, and schema mapping for "Claude talks to Slack" gets written again, slightly differently, for "ChatGPT talks to Slack," and again for "my in-house agent talks to Slack." Multiply that across every application and every system, and you get an M×N tangle of bespoke connectors that nobody wants to maintain.

The Model Context Protocol is Anthropic's answer to that specific problem: "an open-source standard for connecting AI applications to external systems." The canonical framing is a hardware analogy: "Think of MCP like a USB-C port for AI applications." Instead of a custom cable for every device, you build one MCP server for a system, and any MCP-compatible client — Claude Code, Claude Desktop, or your own Agent SDK application — can plug into it.

The host, client, and server model

MCP's architecture has three named roles, and it's worth being precise about which is which, because the terms get used loosely elsewhere:

• MCP Host — the AI application itself (Claude Code, Claude Desktop, or your own agent) that "coordinates and manages one or multiple MCP clients."
• MCP Client — lives inside the host and "maintains a connection to an MCP server," obtaining context for the host to use. There's a dedicated 1:1 client-to-server connection for each server the host talks to.
• MCP Server — "a program that provides context to MCP clients," running either locally over a stdio transport or remotely over a Streamable HTTP transport.

Underneath, MCP separates a data layer from a transport layer. The data layer is JSON-RPC 2.0-based and handles the connection lifecycle, the three primitives below, and notifications; the transport layer is just how those JSON-RPC messages physically travel — stdio for a server running as a local subprocess, Streamable HTTP for one running remotely.

Three primitives: tools, resources, prompts

☺ Like you're 10: Tools are things Claude decides to grab on its own; resources are things the app hands Claude without asking; prompts are things only you can pull off the shelf.

An MCP server can expose context to a client in three distinct shapes, each with a different party deciding when it gets used:

Tools are executable functions the model itself decides to invoke, the same way it would call any function you define directly in a tools array — MCP just means the function's implementation lives in a separate server process instead of your own code. Resources are passive, read-only data: the host application, not the model, decides when to fetch and inject them, each one addressable by a unique URI and MIME type, with support for both fixed "direct resources" and parameterized "resource templates." Prompts are pre-built instruction templates that tell the model how to work with a server's specific tools and resources — because they're user-controlled, they require explicit invocation rather than the model reaching for them on its own, which is exactly how they show up as slash commands in a chat UI.

MCP also defines the reverse direction: capabilities a server can request from the host's client. Sampling (sampling/createMessage) lets a server ask the host's own LLM for a completion without bundling a model of its own; Elicitation (elicitation/create) lets a server request additional input or confirmation from the user mid-task; Logging carries diagnostic messages back to the client.

Wiring an MCP server into an agent

Conceptually, connecting a server to a host follows the same handshake regardless of which client library is doing the talking: negotiate capabilities, discover what the server offers, then call into it when the model decides to.

// 1. Client <-> server handshake (stdio or Streamable HTTP transport)
{"jsonrpc": "2.0", "id": 1, "method": "initialize",
 "params": {"protocolVersion": "...", "capabilities": {}}}

// 2. Client asks what the server offers
{"jsonrpc": "2.0", "id": 2, "method": "tools/list"}
{"jsonrpc": "2.0", "id": 3, "method": "resources/list"}
{"jsonrpc": "2.0", "id": 4, "method": "prompts/list"}

// 3. Claude decides to use a tool; the client invokes it on Claude's behalf
{"jsonrpc": "2.0", "id": 5, "method": "tools/call",
 "params": {"name": "search_flights", "arguments": {"origin": "SFO", "destination": "JFK"}}}

From the Agent SDK side, that handshake is something your host application configures once — pointing at a server, then letting the model treat its tools like any other tool in the loop. The shape of that configuration looks roughly like this (check your SDK's reference for exact class and parameter names, since these evolve):

# Conceptual: wiring an MCP server into an Agent SDK-based agent
agent = ClaudeAgent(
    model="claude-sonnet-5",
    mcp_servers=[
        {"name": "internal-docs", "transport": "stdio", "command": ["python", "docs_server.py"]},
    ],
    allowed_tools=["mcp__internal-docs__*"],
    permission_mode="default",
)

result = agent.run("Find our current refund policy and summarize it.")

// Conceptual: wiring an MCP server into an Agent SDK-based agent
const agent = new ClaudeAgent({
  model: "claude-sonnet-5",
  mcpServers: [
    { name: "internal-docs", transport: "stdio", command: ["python", "docs_server.py"] }
  ],
  allowedTools: ["mcp__internal-docs__*"],
  permissionMode: "default"
});

const result = await agent.run("Find our current refund policy and summarize it.");

Once connected, the server's tools appear to Claude alongside any tools you defined directly — the model doesn't need to know or care that one came from your own code and the other came over an MCP connection. Claude Code and its VS Code extension expose this same wiring through an /mcp command: in the terminal it's a slash command, in the VS Code extension it's an in-panel management dialog for adding and inspecting connected servers.

Build it once, or build it every time

☺ Like you're 10: It's the difference between building one universal charger everyone can use, versus every friend building their own charger for the exact same phone.

The practical case for MCP is what it does to your integration surface as the number of tools and data sources grows.

The savings compound because the protocol is symmetric: you're not just making life easier for your own agent, you're making that system usable, with zero extra integration work, by every other MCP host someone connects to it later.