Claude SDK MCP Helpers: PythonネイティブMCP統合

MCPを通じてClaudeと外部ツールを接続するアプリケーションの構築には、MCPプロトコル型とAnthropic API形式の間で手動の型変換が常に必要でした。v0.84.0で、Anthropic Python SDK — Claude SDKにリブランドされました — にネイティブMCPヘルパーが搭載され、この定型コードが完全に不要になりました。1つの関数呼び出しでMCPツールをClaude APIが理解できる形式に変換し、もう1つの関数でMCPプロンプトメッセージを変換します。この記事では、何がリリースされたか、使い方、そしてSDKの最近の変更点について解説します。

---

SDKリブランド: Anthropic SDKからClaude SDKへ

v0.84.0以降、以前anthropic-sdk-pythonとして知られていたパッケージは、正式にClaude SDKとなりました。PyPIパッケージ名は引き続きanthropicで、インポートパスもfrom anthropic import ...のままなので、既存のコードは一切変更不要です。このリブランドは、AnthropicがClaude Agent SDK、Claude Code、そしてより広範なClaudeエコシステムに合わせて、開発者ツールをClaudeブランドに統合していることを反映しています。

実用的なポイント: 今後Anthropicのドキュメントで「Claude SDK」への言及を見かけた場合、それは既にお使いのpip install anthropicパッケージと同じものを指しています。

---

MCPヘルパーが解決する問題

これらのヘルパーが存在する前は、MCPサーバーとAnthropic APIの統合には変換コードを自分で書く必要がありました。MCPサーバーは独自のスキーマ形式を持つmcp.types.Toolオブジェクトとしてツールを公開します。Anthropic APIはツールをBetaFunctionToolオブジェクトとして期待します。MCPのプロンプトはPromptMessageを使用しますが、AnthropicはMessageParam辞書を期待します。リソースはReadResourceResultとして返されますが、Anthropicのコンテンツブロックが必要です。

すべてのMCP統合で、これらの変換のためのグルーコードを書いて（そしてメンテナンスして）いました。anthropic.lib.tools.mcpの新しいヘルパーがこれらすべてを処理します。

---

新しいMCPヘルパー

このモジュールは5つのパブリック関数をエクスポートします:

ヘルパー	用途
mcp_tool(tool, session)	MCP ToolをAnthropicの同期ツールに変換
async_mcp_tool(tool, session)	MCP ToolをAnthropicの非同期ツールに変換
mcp_message(message)	MCP PromptMessageをAnthropicのメッセージ形式に変換
mcp_resource_to_content(result)	MCPリソースをAnthropicコンテンツブロックに変換
mcp_resource_to_file(result)	MCPリソースをアップロード用ファイルタプルに変換

すべての関数は、Anthropicのプロンプトキャッシュ用にオプションのcache_controlパラメータも受け付けます。

async_mcp_tool — コアヘルパー

最も頻繁に使う関数です。MCPのTool定義とClientSessionを受け取り、Anthropicのtool_runner()が直接実行できるBetaAsyncFunctionToolを返します。Claudeがツールの呼び出しを決定すると、ヘルパーは自動的にMCPサーバーに呼び出しを転送し、結果を変換して返します。

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]

この1行のリスト内包表記で、以前は30-50行かかっていた手動のスキーママッピング、ツールディスパッチ、結果変換を置き換えます。

mcp_tool — 同期版

同期版は同じように動作しますが、内部的にanyio.from_threadを使用して、同期コードから非同期MCPクライアントを呼び出します。アプリケーションが非同期でない場合はこちらを使用してください:

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 — プロンプト変換

MCPサーバーは再利用可能なプロンプトを公開できます。mcp_message()ヘルパーはMCPのPromptMessage形式をAnthropicのメッセージ形式に変換します:

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 — リソース統合

MCPサーバーがリソース（ファイル、ドキュメント、データ）を提供する場合、このヘルパーはそれらをメッセージに含めることができるAnthropicコンテンツブロックに変換します。テキスト、画像（JPEG、PNG、GIF、WebP）、PDFに対応しています:

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"},
        ],
    }],
)

---

完全な動作サンプル

MCPファイルシステムサーバーに接続し、ツールを変換し、Claudeがファイルの一覧表示と読み取りを行える会話を実行するエンドツーエンドの完全な例を示します:

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())

tool_runner()はツール使用ループ全体を処理します: Claudeがツール呼び出しをリクエストし、ランナーがMCPヘルパーを介して実行し、結果をフィードバックし、Claudeが最終レスポンスを生成するまで続けます。手動でのループ管理は不要です。

---

高度なオプション

mcp_tool()とasync_mcp_tool()ヘルパーは、基本的なもの以外にいくつかのオプションパラメータを受け付けます:

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: ツール定義にAnthropicのキャッシュ制御ディレクティブを付与します。繰り返し呼び出しのレイテンシ削減に有用です。
• defer_loading: Trueの場合、ツール定義は初期システムプロンプトに含まれません。多くのツールがあるがプロンプトサイズを削減したい場合に有用です。
• strict: ツール名と入力に対する厳密なスキーマ検証を有効にします。
• input_examples: Claudeがツールの正しい使い方を理解するのに役立つ入力例を提供します。

---

エラーハンドリング

ヘルパーは、MCP値をClaude APIがサポートする形式に変換できない場合にUnsupportedMCPValueErrorを発生させます。これはサポートされていないコンテンツタイプ（オーディオなど）やサポートされていないMIMEタイプの場合に発生します:

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}")

MCPツール呼び出しがエラーを返した場合（CallToolResult.isErrorがTrueの場合）、ヘルパーはToolErrorを発生させ、tool_runner()がClaudeにエラーを自動的に報告して処理します。

---

インストール

MCPサポート付きでSDKをインストールします:

pip install anthropic[mcp]

これにより、追加依存関係としてmcpパッケージがインストールされます。MCPサポートにはPython 3.10以上が必要です — MCP SDK自体が古いPythonバージョンをサポートしていません。

既にanthropicがインストールされている場合は、アップグレードして最新のヘルパーを取得してください:

pip install --upgrade anthropic[mcp]

---

その他の最近のSDKアップデート

MCPヘルパーは、v0.77以降のSDK改善の一環です。他にリリースされた内容を紹介します:

v0.83 — 自動キャッシング

トップレベルのキャッシュ制御サポート。個々のメッセージにキャッシュブレークポイントを手動でアノテーションする代わりに、リクエストレベルでキャッシュ動作を設定でき、SDKが配置を自動的に処理します。

v0.80 — Sonnet 4.6

Claude Sonnet 4.6のサポートが追加されました。新しいモデル識別子やSonnet固有のパラメータを含みます。

v0.78-0.79 — Opus 4.6とFast Mode

100万トークンのコンテキストウィンドウ、エフォートチューニング（fast/normal/thorough）、新しいAgent Teams機能を備えたClaude Opus 4.6のサポート。SDKにはこれらの機能に必要なパラメータと型定義が追加されました。

v0.77 — Structured Outputs

構造化出力のネイティブサポート。Pydanticモデルまたはjsonスキーマを定義して、Claudeのレスポンスがそれに準拠するように指定できます。構造化データ抽出のためにClaudeの出力を事後的にパースする必要がなくなります。

---

なぜこれが重要なのか

MCPは、AIモデルを外部ツールやデータソースに接続するための標準プロトコルになりつつあります。これらのヘルパーが登場する前は、MCPツールをClaudeで使用したいすべてのPythonアプリケーションが独自の変換レイヤーを実装する必要がありました — MCPツールスキーマをAnthropicの形式にマッピングし、ツール呼び出しをMCPサーバーにディスパッチし、結果を変換して返す必要がありました。これは繰り返し作業であり、エラーが発生しやすく、MCPの仕様またはAnthropic APIが進化するたびにメンテナンスの負担が生じていました。

ネイティブヘルパーにより、統合はツールごとに1つの関数呼び出しに集約されます。SDKが変換ロジックを管理し、API変更との同期を維持し、アプリケーション開発者が自分で管理する必要があるエッジケース（サポートされていないコンテンツタイプ、エラー伝播、リソースMIMEタイプ検出）を処理します。

MCPを活用したClaudeアプリケーションを構築しているチーム — ファイルシステムアクセスを持つコーディングアシスタント、データベースツールを持つデータパイプライン、CRM統合を持つカスタマーサポートエージェントなど — にとって、これはグルーコードの削減と迅速なイテレーションを意味します。

---

リソース

• Anthropic Python SDK on GitHub
• MCP Helpersドキュメント
• MCP仕様
• 完全なサンプル: mcp_tool_runner.py