MCP公式Python SDK、ツールの例外がクライアントに届かない。更新後はToolErrorへ

MCP Python SDK v2.1.0 が 2026 年 8 月 24 日に公開され、ハンドラ例外の見え方と構造化出力の扱いが変わりました。更新前に確認したい動作変更を整理します。

📖 この記事で分かること

• v2.1.0でハンドラ例外の扱いが変わった点
• モデルに見せる文言はToolErrorで送る必要
• 戻り値の型注釈で構造化出力が消える条件
• 4 MiB上限がSSEとOAuthにも及ぶこと

💡 知っておきたい用語

• MCP【エムシーピー】: AIモデルと外部ツールをつなぐ共通の約束事。アプリごとに接続方法を作り直さずに済む配線規格のようなもの。

最終更新日: 2026年8月25日

▶ 公式ページ

• MCP Python SDK v2.1.0 リリースノート（GitHub）
• modelcontextprotocol/python-sdk リポジトリ（GitHub）
• MCP Python SDK v1.29.1 リリースノート（GitHub）

MCP公式Python SDK v2.1.0が公開

この記事のポイント

• Model Context Protocolの公式Python SDK v2.1.0が2026年8月24日（協定世界時19時、日本時間25日午前4時ごろ）に公開されました（2026年8月時点）。
• ハンドラの想定外の例外はクライアントに中身が渡らず、Error executing tool <name> だけが返ります。
• モデルに読ませたい文言は ToolError / ResourceError で送出する必要があります。

Model Context Protocol（MCP）の公式Python SDKが、v2.1.0（2026年8月時点）を公開しました。v2系は2026年7月28日のv2.0.0から始まっており、今回はその系列で最初の機能リリースにあたります。同じ日にv1.29.1も出ており、1系の保守ラインと2系が並行して手入れされています。

追加機能より先に確認したいのは、既存のサーバ実装の挙動が変わる2点です。エラーの見え方と、構造化出力の有無が対象になります。

更新前に確認したい2つの動作変更

エラー文面と戻り値の型注釈に依存している実装は、更新後に見直しが要ります。

1つ目は例外の扱いです（PR #3314）。ツール・リソース・プロンプトのハンドラで想定外の例外が発生した場合、サーバ側ではERRORレベルでトレースバック付きに1回ログされます。一方でクライアントに渡るのは Error executing tool <name>（リソースとプロンプトは相当する文言）だけになり、例外の中身は伝わりません。モデルに読ませたいメッセージがあるときは ToolError または ResourceError を送出します。こちらはクライアントに届き、トレースバックなしでINFOログに記録されます。例外文をそのまま説明としてモデルに渡していた実装は、送出する例外クラスの置き換えが必要です。

2つ目は構造化出力です（PR #3320）。戻り値を TextContent / EmbeddedResource / Image / Audio、またはそれらのリストやユニオンとして型注釈したツールは、outputSchema を広告せず structuredContent も返さなくなりました。content は変更されません。従来の形を保ちたい場合は structured_output=True を渡します。

追加機能とリクエスト上限の適用範囲

クライアント側の記述量が減り、ボディサイズ上限の適用範囲が広がりました。

Client が StdioServerParameters を直接受け取れるようになりました（PR #3321）。リリースノートには Client(StdioServerParameters(command="uv", args=["run", "server.py"])) という書き方が示されています。プロンプト側では、メッセージが Image と Audio を受け付け、プロンプト関数が素のコンテンツブロックを返せるようになりました。あわせて Message / UserMessage / AssistantMessage が mcp.server.mcpserver からエクスポートされます（PR #3320）。

上限まわりでは、4 MiBのリクエストボディ上限がSSEトランスポートとOAuthエンドポイントにも適用されるようになりました（2026年8月時点、PR #3336）。SseServerTransport と MCPServer.sse_app() は max_request_body_size を受け取ります。SSEのメッセージエンドポイントは、POST以外のリクエストに405を返します。

互換性まわりの修正

古いクライアントやセッションを抱えた環境で、失敗していた経路が通るようになりました。

TypedDictのツール結果では、NotRequired のキーがnullとして直列化されず省略されます。Python 3.10で登録が失敗する問題も解消しました（#3224、#3227）。再帰的な戻り値型にはobjectをルートとする outputSchema が付与され、2026年以前のクライアントでも受理されます（#3337）。

プロトコルの2026-07-28リビジョンをHTTPで扱う場合、notifications/cancelled のようなPOSTされた通知が400で拒否されず202で受理されます（#3324）。2026年以前のセッションは、後続リビジョンのキャッシュヒントを無視するようになり、list_tools() が失敗しなくなりました（#3223）。ドキュメントは12言語で公開されています（#3280）。

編集部の見方

編集部は、今回のリリースで最初に手を付けるべきは例外の扱いだと考えます。

• 根拠1: 挙動が変わるのはサーバのログではなくクライアントに返る文面です。テストがログだけを見ている場合、変更に気づかないまま本番でモデルへの情報が減ります。
• 根拠2: 対処が ToolError / ResourceError の送出という書き換えで済み、影響範囲が例外まわりに限定されています。段階的に直せます。
• 根拠3: 例外の中身がそのまま外に出ない設計は、スタックトレースの露出を避ける方向の変更でもあります。運用上は元に戻すより追随するほうが筋が通ります。

この見方が変わる条件は、structured_output の既定変更が想定より広く効くと分かった場合です。構造化出力を前提にした呼び出し側が多い実装では、そちらの修正量が上回ります。

なお公開日から日が浅く、1系と2系の並行メンテナンスが続いています。1系を使い続けている場合は、同日公開のv1.29.1側の内容も確認できます。

よくある質問

Q: v2.1.0はv2系の登場を意味しますか

A: いいえ。v2.0.0が2026年7月28日に公開されており、v2.1.0はその系列で最初の機能リリースです。

Q: 更新するとツールのエラーは一切見えなくなりますか

A: サーバ側にはERRORレベルでトレースバック付きに記録が残ります。クライアントに渡らなくなるのは例外の中身で、ToolError / ResourceError で送出した文言は届きます。

Q: 構造化出力を今までどおり返したい場合はどうしますか

A: structured_output=True を渡します。これを指定しない場合、対象の型注釈が付いたツールは outputSchema を広告せず structuredContent も返しません。

まとめ

MCPの公式Python SDK v2.1.0は、ハンドラの想定外の例外をクライアントに渡さない挙動と、特定の型注釈で構造化出力を返さない挙動という2つの動作変更を含みます。前者は ToolError / ResourceError の送出、後者は structured_output=True の指定で従来に近い形を保てます。あわせて4 MiBのリクエストボディ上限がSSEとOAuthのエンドポイントにも適用され、古いクライアント向けの互換性修正も入りました。更新の前に、エラー文面と戻り値の型注釈に依存した実装を洗い出す作業が要ります。

【用語解説】

• SSE: サーバからクライアントへ一方向に更新を流し続ける通信方式。ページを再読み込みせずに続きが届く仕組み。
• outputSchema: ツールが返す値の構造をあらかじめ相手に知らせる定義。届いた値をそのまま部品として扱えるようにするための取り決め。
• TypedDict: Pythonで辞書のキーと値の型を決めておく書き方。想定外のキーや型を早い段階で見つけやすくなる。

引用元:

• [1] MCP Python SDK v2.1.0 リリースノート（GitHub）
• [2] MCP Python SDK v1.29.1 リリースノート（GitHub）
• [3] modelcontextprotocol/python-sdk リポジトリ（GitHub）

この記事について: AI 支援で執筆、編集部が事実確認・編集しています。誤りや追加情報があれば Contact よりお知らせください。