feat(helpers): add conversion helpers for MCP tools, prompts, and resources (#1383)

Author: felixfbecker

examples/mcp_tool_runner.py

@@ -0,0 +1,54 @@
+"""Example showing how to use MCP helpers with tool_runner().
+
+Connects to an MCP server, converts its tools to Anthropic-compatible tools
+using async_mcp_tool(), and runs them in a tool_runner() loop.
+
+Requires: pip install anthropic[mcp]
+Requires: Python 3.10+
+"""
+
+import asyncio
+
+import rich
+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:
+    # Connect to a local MCP server via stdio
+    # This example uses the MCP filesystem server; replace with your own server
+    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()
+
+            # List available tools from the MCP server and convert them
+            tools_result = await mcp_client.list_tools()
+            tools = [async_mcp_tool(t, mcp_client) for t in tools_result.tools]
+
+            print(f"Connected to MCP server with {len(tools)} tools:")
+            for tool in tools:
+                print(f"  - {tool.name}")
+            print()
+
+            # Run a conversation with tool_runner()
+            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"}],
+            )
+            async for message in runner:
+                rich.print(message)
+
+
+asyncio.run(main())

helpers.md

@@ -28,7 +28,7 @@ The stream will be cancelled when the context manager exits but you can also clo
 
 See an example of streaming helpers in action in [`examples/messages_stream.py`](examples/messages_stream.py).
 
-> [!NOTE]  
+> [!NOTE]
 > The synchronous client has the same interface just without `async/await`.
 
 ### Lenses
@@ -131,7 +131,91 @@ Blocks until the stream has been read to completion and returns the accumulated
 
 #### `await .get_final_text()`
 
-> [!NOTE]  
+> [!NOTE]
 > Currently the API will only ever return 1 content block
 
 Blocks until the stream has been read to completion and returns all `text` content blocks concatenated together.
+
+## MCP Helpers
+
+This SDK provides helpers for integrating with [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) servers. These helpers convert MCP types to Anthropic API types, reducing boilerplate when working with MCP tools, prompts, and resources.
+
+> **Note:** The Claude API also supports an [`mcp_servers` parameter](https://docs.anthropic.com/en/docs/agents-and-tools/mcp) that lets Claude connect directly to remote MCP servers.
+>
+> - Use `mcp_servers` when you have remote servers accessible via URL and only need tool support.
+> - Use the MCP helpers when you need local MCP servers, prompts, resources, or more control over the MCP connection.
+
+> **Requires:** `pip install anthropic[mcp]` (Python 3.10+)
+
+### Using MCP tools with tool_runner
+
+```py
+from anthropic import AsyncAnthropic
+from anthropic.lib.tools.mcp import async_mcp_tool
+from mcp import ClientSession
+from mcp.client.stdio import stdio_client, StdioServerParameters
+
+client = AsyncAnthropic()
+
+async with stdio_client(StdioServerParameters(command="mcp-server")) as (read, write):
+    async with ClientSession(read, write) as mcp_client:
+        await mcp_client.initialize()
+
+        tools_result = await mcp_client.list_tools()
+        runner = await client.beta.messages.tool_runner(
+            model="claude-sonnet-4-20250514",
+            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)
+```
+
+> [!TIP]
+> If you're using the sync client, replace `async_mcp_tool` with `mcp_tool`.
+
+### Using MCP prompts
+
+```py
+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-4-20250514",
+    max_tokens=1024,
+    messages=[mcp_message(m) for m in prompt.messages],
+)
+```
+
+### Using MCP resources as content
+
+```py
+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-20250514",
+    max_tokens=1024,
+    messages=[{
+        "role": "user",
+        "content": [
+            mcp_resource_to_content(resource),
+            {"type": "text", "text": "Summarize this document"},
+        ],
+    }],
+)
+```
+
+### Uploading MCP resources as files
+
+```py
+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))
+```
+
+### Error handling
+
+The conversion functions raise `UnsupportedMCPValueError` if an MCP value cannot be converted to a format supported by the Claude API (e.g., unsupported content type like audio, unsupported MIME type).

pyproject.toml

@@ -42,6 +42,7 @@ classifiers = [
 aiohttp = ["aiohttp", "httpx_aiohttp>=0.1.9"]
 vertex = ["google-auth[requests] >=2, <3"]
 bedrock = ["boto3 >= 1.28.57", "botocore >= 1.31.57"]
+mcp = ["mcp>=1.0; python_version >= '3.10'"]
 
 [project.urls]
 Homepage = "https://github.com/anthropics/anthropic-sdk-python"
@@ -50,11 +51,17 @@ Repository = "https://github.com/anthropics/anthropic-sdk-python"
 [tool.uv]
 managed = true
 required-version = ">=0.9"
+# Ensure the lockfile always uses public PyPI, regardless of contributor's global uv config
+index = [{ url = "https://pypi.org/simple", default = true }]
 conflicts = [
     [
       { group = "pydantic-v1" },
       { group = "pydantic-v2" },
     ],
+    [
+      { group = "pydantic-v1" },
+      { extra = "mcp" },
+    ],
 ]
 
 [dependency-groups]
@@ -147,6 +154,7 @@ exclude = [
     "_dev",
     ".venv",
     ".nox",
+    "examples/mcp_tool_runner.py",  # mcp requires Python 3.10+, lint runs on 3.9
 ]
 
 reportImplicitOverride = true
@@ -165,7 +173,7 @@ show_error_codes = true
 #
 # We also exclude our `tests` as mypy doesn't always infer
 # types correctly and Pyright will still catch any type errors.
-exclude = ['src/anthropic/_files.py', '_dev/.*.py', 'tests/.*', 'examples/mcp_server_weather.py', 'examples/tools_with_mcp.py', 'examples/memory/basic.py', 'src/anthropic/lib/_parse/_transform.py', 'src/anthropic/lib/tools/_beta_functions.py']
+exclude = ['src/anthropic/_files.py', '_dev/.*.py', 'tests/.*', 'examples/mcp_server_weather.py', 'examples/mcp_tool_runner.py', 'examples/tools_with_mcp.py', 'examples/memory/basic.py', 'src/anthropic/lib/_parse/_transform.py', 'src/anthropic/lib/tools/_beta_functions.py']
 
 strict_equality = true
 implicit_reexport = true
@@ -210,6 +218,10 @@ ignore_missing_imports = true
 module = "anthropic.lib.vertex._auth"
 disallow_untyped_calls = false
 
+[[tool.mypy.overrides]]
+module = "tests.lib.tools.test_mcp_tool"
+follow_imports = "skip"
+
 [tool.ruff]
 line-length = 120
 output-format = "grouped"

scripts/test

@@ -66,8 +66,9 @@ function run_tests() {
     # Skip Pydantic v1 tests on latest Python (not supported)
     if [[ "$UV_PYTHON" != "$PY_VERSION_MAX" ]]; then
         echo "==> Running tests with Pydantic v1"
-        uv run --isolated --all-extras --group=pydantic-v1 pytest "$@"
+        uv run --isolated --all-extras --no-extra=mcp --group=pydantic-v1 pytest "$@"
     fi
+
 }
 
 # If UV_PYTHON is already set in the environment, just run the command once

src/anthropic/_utils/_typing.py

@@ -53,7 +53,7 @@ def is_typevar(typ: type) -> bool:
 
 _TYPE_ALIAS_TYPES: tuple[type[typing_extensions.TypeAliasType], ...] = (typing_extensions.TypeAliasType,)
 if sys.version_info >= (3, 12):
-    _TYPE_ALIAS_TYPES = (*_TYPE_ALIAS_TYPES, typing.TypeAliasType)
+    _TYPE_ALIAS_TYPES = (*_TYPE_ALIAS_TYPES, typing.TypeAliasType)  # type: ignore[arg-type]
 
 
 def is_type_alias_type(tp: Any, /) -> TypeIs[typing_extensions.TypeAliasType]:

src/anthropic/lib/_stainless_helpers.py

@@ -0,0 +1,75 @@
+"""Tracking for SDK helper usage via the x-stainless-helper header."""
+
+from __future__ import annotations
+
+from typing import Any, Dict, cast
+
+_HELPER_ATTR = "_stainless_helper"
+
+
+def tag_helper(obj: Any, name: str) -> None:
+    """Mark an object as created by a named SDK helper."""
+    try:
+        object.__setattr__(obj, _HELPER_ATTR, name)
+    except (AttributeError, TypeError):
+        pass
+
+
+def get_helper_tag(obj: object) -> str | None:
+    """Get the helper name from an object, if any."""
+    return getattr(obj, _HELPER_ATTR, None)  # type: ignore[return-value]
+
+
+def collect_helpers(
+    tools: Any = None,
+    messages: Any = None,
+) -> list[str]:
+    """Collect deduplicated helper names from tools and messages."""
+    helpers: set[str] = set()
+
+    if tools:
+        for tool in tools:
+            tag = get_helper_tag(tool)
+            if tag is not None:
+                helpers.add(tag)
+
+    if messages:
+        for message in messages:
+            tag = get_helper_tag(message)
+            if tag is not None:
+                helpers.add(tag)
+
+            # Check content blocks within messages
+            if isinstance(message, dict):
+                blocks: Any = cast(Dict[str, Any], message).get("content")
+            else:
+                blocks = getattr(message, "content", None)
+            if isinstance(blocks, list):
+                for block in cast(list[object], blocks):
+                    tag = get_helper_tag(block)
+                    if tag is not None:
+                        helpers.add(tag)
+
+    return list(helpers)
+
+
+def stainless_helper_header(
+    tools: Any = None,
+    messages: Any = None,
+) -> dict[str, str]:
+    """Build x-stainless-helper header dict from tools and messages.
+
+    Returns an empty dict if no helpers are found.
+    """
+    helpers = collect_helpers(tools, messages)
+    if not helpers:
+        return {}
+    return {"x-stainless-helper": ", ".join(helpers)}
+
+
+def stainless_helper_header_from_file(file: object) -> dict[str, str]:
+    """Build x-stainless-helper header dict from a file object."""
+    tag = get_helper_tag(file)
+    if tag is None:
+        return {}
+    return {"x-stainless-helper": tag}

src/anthropic/lib/tools/__init__.py

@@ -1,5 +1,6 @@
 from ._beta_runner import BetaToolRunner, BetaAsyncToolRunner, BetaStreamingToolRunner, BetaAsyncStreamingToolRunner
 from ._beta_functions import (
+    ToolError,
     BetaFunctionTool,
     BetaAsyncFunctionTool,
     BetaBuiltinFunctionTool,
@@ -24,4 +25,5 @@
     "BetaFunctionToolResultType",
     "BetaAbstractMemoryTool",
     "BetaAsyncAbstractMemoryTool",
+    "ToolError",
 ]