Claude SDK MCP Helpers: Native MCP Integration for Python

Building applications that connect Claude to external tools through MCP has always required manual type conversion between the MCP protocol types and the Anthropic API format. With v0.84.0, the Anthropic Python SDK — now rebranded as the Claude SDK — ships native MCP helpers that eliminate that boilerplate entirely. One function call converts an MCP tool into a format Claude’s API understands, and another converts MCP prompt messages. This article covers what shipped, how to use it, and what else has changed in the SDK recently.

The SDK Rebrand: Anthropic SDK Becomes Claude SDK

Starting with v0.84.0, the package formerly known as anthropic-sdk-python is now officially the Claude SDK. The PyPI package name remains anthropic and the import path is still from anthropic import ..., so existing code requires zero changes. The rebrand reflects Anthropic’s consolidation of developer tooling under the Claude brand, aligning the Python SDK with the Claude Agent SDK, Claude Code, and the broader Claude ecosystem.

The practical takeaway: if you see references to “Claude SDK” in Anthropic’s docs going forward, they mean the same pip install anthropic package you already use.

The Problem MCP Helpers Solve

Before these helpers existed, integrating an MCP server with the Anthropic API meant writing conversion code yourself. An MCP server exposes tools as mcp.types.Tool objects with their own schema format. The Anthropic API expects tools as BetaFunctionTool objects. Prompts from MCP use PromptMessage, while Anthropic expects MessageParam dicts. Resources come back as ReadResourceResult, but you need Anthropic content blocks.

Every MCP integration had to write (and maintain) glue code for these conversions. The new helpers in anthropic.lib.tools.mcp handle all of it.

The New MCP Helpers

The module exports five public functions:

Helper	Purpose
`mcp_tool(tool, session)`	Convert MCP Tool to sync Anthropic tool
`async_mcp_tool(tool, session)`	Convert MCP Tool to async Anthropic tool
`mcp_message(message)`	Convert MCP PromptMessage to Anthropic message format
`mcp_resource_to_content(result)`	Convert MCP resource to Anthropic content block
`mcp_resource_to_file(result)`	Convert MCP resource to a file tuple for upload

All functions also accept an optional cache_control parameter for Anthropic’s prompt caching.

async_mcp_tool — The Core Helper

This is the function you will reach for most often. It takes an MCP Tool definition and a ClientSession, and returns a BetaAsyncFunctionTool that the Anthropic tool_runner() can execute directly. When Claude decides to call the tool, the helper automatically forwards the call to the MCP server and converts the result back.

from anthropic.lib.tools.mcp import async_mcp_tool

# Convert all MCP tools in one line
tools = [async_mcp_tool(t, mcp_client) for t in tools_result.tools]

That single list comprehension replaces what used to be 30-50 lines of manual schema mapping, tool dispatch, and result conversion.

mcp_tool — Sync Version

The synchronous variant works identically but uses anyio.from_thread internally to call the async MCP client from synchronous code. Use this when your application is not async:

from anthropic.lib.tools.mcp import mcp_tool

tools = [mcp_tool(t, mcp_client) for t in tools_result.tools]
runner = client.beta.messages.tool_runner(
    model="claude-sonnet-4-5-20250929",
    max_tokens=1024,
    tools=tools,
    messages=[{"role": "user", "content": "List files in /tmp"}],
)

mcp_message — Prompt Conversion

MCP servers can expose reusable prompts. The mcp_message() helper converts MCP’s PromptMessage format to Anthropic’s message format:

from anthropic.lib.tools.mcp import mcp_message

prompt = await mcp_client.get_prompt(name="code-review")
response = await client.beta.messages.create(
    model="claude-sonnet-4-5-20250929",
    max_tokens=1024,
    messages=[mcp_message(m) for m in prompt.messages],
)

mcp_resource_to_content — Resource Integration

When an MCP server provides resources (files, documents, data), this helper converts them to Anthropic content blocks you can include in messages. It handles text, images (JPEG, PNG, GIF, WebP), and PDFs:

from anthropic.lib.tools.mcp import mcp_resource_to_content

resource = await mcp_client.read_resource(uri="file:///path/to/doc.txt")
response = await client.beta.messages.create(
    model="claude-sonnet-4-5-20250929",
    max_tokens=1024,
    messages=[{
        "role": "user",
        "content": [
            mcp_resource_to_content(resource),
            {"type": "text", "text": "Summarize this document"},
        ],
    }],
)

Complete Working Example

Here is a full end-to-end example that connects to the MCP filesystem server, converts its tools, and runs a conversation where Claude can list and read files:

import asyncio

from mcp import ClientSession
from mcp.client.stdio import StdioServerParameters, stdio_client

from anthropic import AsyncAnthropic
from anthropic.lib.tools.mcp import async_mcp_tool

client = AsyncAnthropic()


async def main() -> None:
    server_params = StdioServerParameters(
        command="npx",
        args=["-y", "@modelcontextprotocol/server-filesystem", "/tmp"],
    )

    async with stdio_client(server_params) as (read, write):
        async with ClientSession(read, write) as mcp_client:
            await mcp_client.initialize()

            # Convert all MCP tools to Anthropic format
            tools_result = await mcp_client.list_tools()
            tools = [async_mcp_tool(t, mcp_client) for t in tools_result.tools]

            print(f"Connected with {len(tools)} tools:")
            for tool in tools:
                print(f"  - {tool.name}")

            # Run the conversation -- tool_runner handles the loop
            runner = client.beta.messages.tool_runner(
                model="claude-sonnet-4-5-20250929",
                max_tokens=1024,
                tools=tools,
                messages=[{
                    "role": "user",
                    "content": "List the files in /tmp and tell me what you find",
                }],
            )
            async for message in runner:
                print(message)


asyncio.run(main())

The tool_runner() handles the complete tool use loop: Claude requests a tool call, the runner executes it via the MCP helper, feeds the result back, and continues until Claude produces a final response. No manual loop management needed.

Advanced Options

The mcp_tool() and async_mcp_tool() helpers accept several optional parameters beyond the basics:

tool = async_mcp_tool(
    t,
    mcp_client,
    cache_control={"type": "ephemeral"},  # Enable prompt caching
    defer_loading=True,       # Exclude from initial system prompt
    strict=True,              # Enforce schema validation
    input_examples=[          # Provide example inputs
        {"path": "/tmp", "recursive": False}
    ],
)

cache_control: Attach Anthropic’s cache control directives to the tool definition, useful for reducing latency on repeated calls.
defer_loading: When True, the tool definition is not included in the initial system prompt. Useful when you have many tools but want to reduce prompt size.
strict: Enables strict schema validation on tool names and inputs.
input_examples: Provide example inputs to help Claude understand how to use the tool correctly.

Error Handling

The helpers raise UnsupportedMCPValueError when an MCP value cannot be converted to a format Claude’s API supports. This happens with unsupported content types (like audio) or unsupported MIME types:

from anthropic.lib.tools.mcp import async_mcp_tool, UnsupportedMCPValueError

try:
    tools = [async_mcp_tool(t, mcp_client) for t in tools_result.tools]
except UnsupportedMCPValueError as e:
    print(f"Tool conversion failed: {e}")

When an MCP tool call returns an error (i.e., CallToolResult.isError is True), the helper raises a ToolError that the tool_runner() handles automatically by reporting the error back to Claude.

Installation

Install the SDK with MCP support:

pip install anthropic[mcp]

This pulls in the mcp package as an extra dependency. Python 3.10 or higher is required for MCP support — the MCP SDK itself does not support older Python versions.

If you already have anthropic installed, upgrade to get the latest helpers:

pip install --upgrade anthropic[mcp]

Other Recent SDK Updates

The MCP helpers are part of a broader wave of SDK improvements since v0.77. Here is what else has shipped:

v0.83 — Automatic Caching

Top-level cache control support. Instead of manually annotating individual messages with cache breakpoints, you can now set caching behavior at the request level, and the SDK handles placement automatically.

v0.80 — Sonnet 4.6

Added support for Claude Sonnet 4.6, including the new model identifiers and any Sonnet-specific parameters.

v0.78-0.79 — Opus 4.6 and Fast Mode

Support for Claude Opus 4.6 with its 1M token context window, effort tuning (fast/normal/thorough), and the new Agent Teams capabilities. The SDK added the necessary parameters and type definitions for these features.

v0.77 — Structured Outputs

Native support for structured outputs, allowing you to define Pydantic models or JSON schemas that Claude’s responses must conform to. This eliminates the need for post-hoc parsing of Claude’s output for structured data extraction.

Why This Matters

MCP is becoming the standard protocol for connecting AI models to external tools and data sources. Before these helpers, every Python application that wanted to use MCP tools with Claude had to implement its own conversion layer — mapping MCP tool schemas to Anthropic’s format, dispatching tool calls to the MCP server, and converting results back. This was repetitive, error-prone, and created maintenance burden when either the MCP spec or the Anthropic API evolved.

With the native helpers, the integration collapses to a single function call per tool. The SDK owns the conversion logic, keeps it in sync with API changes, and handles edge cases (unsupported content types, error propagation, resource MIME type detection) that application developers would otherwise need to manage themselves.

For teams building MCP-powered Claude applications — whether that is a coding assistant with filesystem access, a data pipeline with database tools, or a customer support agent with CRM integration — this means less glue code and faster iteration.