MCP integration helpers in anthropic.lib.tools.mcp convert MCP tools, prompts, and resources into Anthropic SDK types for use with the tool runner and Files API, with async_mcp_tool, mcp_message, and mcp_resource_to_file as the entry points. The module supports both MCP SDK v1 and v2 field naming conventions and validates content types, raising UnsupportedMCPValueError for unsupported formats like audio or unsupported image MIME types. MCP (Model Context Protocol) is an open protocol that standardizes communication between AI models and external tools, prompt libraries, and data resources through a client/server interface.
MCP integration helpers live in src/anthropic/lib/tools/mcp.py, part of the optional anthropic[mcp] extra, and require Python 3.10 or higher; if the mcp package is absent the module raises an ImportError with the instruction pip install anthropic[mcp].[1][2] The recommended import is from anthropic.lib.tools.mcp import mcp_tool, async_mcp_tool, mcp_message; the full public API also includes mcp_content, mcp_resource_to_content, mcp_resource_to_file, and UnsupportedMCPValueError.[1]
Internally, mcp.py supports both MCP SDK v1 (camelCase field names: inputSchema, mimeType, isError, structuredContent) and MCP SDK v2 (snake_case: input_schema, mime_type, is_error, structured_content) through the _mcp_field_v1_or_v2 helper.[1]
Canonical usage converts an MCP tool list with async_mcp_tool and passes the results to client.beta.messages.tool_runner — see Tool runner for the runner API:
tools_result = await mcp_client.list_tools()
runner = await client.beta.messages.tool_runner(
model="claude-sonnet-5",
max_tokens=1024,
messages=[{"role": "user", "content": "Use the available tools"}],
tools=[async_mcp_tool(t, mcp_client) for t in tools_result.tools],
)
async for message in runner:
print(message)
mcp_content converts a single MCP ContentBlock to an Anthropic beta content block, handling TextContent, ImageContent, and EmbeddedResource; it accepts an optional cache_control: BetaCacheControlEphemeralParam parameter that is forwarded onto the returned block.[1] mcp_content raises UnsupportedMCPValueError for audio, resource_link, and unknown content types, and also raises it when an ImageContent block carries a MIME type outside the supported set of image/jpeg, image/png, image/gif, and image/webp.[1][2] For image or PDF resources, _resource_contents_to_block requires BlobResourceContents and raises UnsupportedMCPValueError if TextResourceContents is found instead, because those MIME types require binary data.[1] Text resources delivered as BlobResourceContents are base64-decoded and then decoded as UTF-8 before being placed into a BetaPlainTextSourceParam.[1]
mcp_message converts an MCP PromptMessage to an Anthropic BetaMessageParam-compatible dict by wrapping the message's single content block (via mcp_content) in a list under the content key, preserving the original role.[1]
MCP prompts can be converted to Anthropic messages using mcp_message:
from anthropic.lib.tools.mcp import mcp_message
prompt = await mcp_client.get_prompt(name="my-prompt")
response = await client.beta.messages.create(
model="claude-sonnet-5",
max_tokens=1024,
messages=[mcp_message(m) for m in prompt.messages],
)
mcp_resource_to_content iterates result.contents and returns a content block for the first item with a supported MIME type (text/*, application/pdf, or a supported image type); it raises UnsupportedMCPValueError if the list is empty or no item has a supported MIME type.[1] mcp_resource_to_file converts MCP resource contents to a (filename, content_bytes, mime_type) tuple compatible with the SDK's FileTypes, extracting the filename from the URI path; it always uses the first item in result.contents and raises UnsupportedMCPValueError if that array is empty.[1]
MCP resources can be uploaded to the Files API by passing mcp_resource_to_file(resource) directly to client.beta.files.upload:
from anthropic.lib.tools.mcp import mcp_resource_to_file
resource = await mcp_client.read_resource(uri="file:///path/to/data.json")
uploaded = await client.beta.files.upload(file=mcp_resource_to_file(resource))
All content blocks produced by the MCP helpers are _TaggedDict instances — a dict subclass that carries a _stainless_helper attribute (set via tag_helper) for SDK telemetry; the attribute does not appear in JSON serialization.[1]
Sources