MCPのツール定義がJSON Schema 2020-12の全機能に対応

MCPの2026-07-28仕様改訂で、ツール定義のinputSchemaとoutputSchemaが受け付けるJSON Schemaのキーワード範囲が広がりました。$refやanyOf・oneOf・allOfといった合成キーワードを使ったスキーマも、仕様の想定内として明記されています。同時にstructuredContentはJSONオブジェクト限定から任意のJSON値を返せるようになり、$refの解決と合成キーワードの計算量には新しく上限を課す要件が加わりました。SEP-2106として提案されたこの変更は、MCPサーバーを実装・保守する開発者と、そのサーバーをClaude Codeで動かす利用者の両方に関わります。

MCPツール定義のJSON Schemaで何が変わったか

MCPのツール定義とは、サーバーがtools/listで返すinputSchema(入力パラメータ)とoutputSchema(出力構造)という2つのJSON Schemaのことです。2026-07-28版の変更点(SEP-2106)は3つに整理できます。inputSchema・outputSchemaが使えるJSON Schema 2020-12のキーワード範囲を広げたこと、structuredContentが返せる型を広げたこと、そして$refの解決と合成キーワードの計算量に新しい安全要件を課したことです。

デフォルトのスキーマ方言がJSON Schema 2020-12であること自体は、1つ前の2025-11-25版から変わっていません。変わったのは、ツール定義がそのキーワードをどこまで受け入れるかという範囲です。以前の仕様は受け入れ範囲がより限定的で、$refや合成キーワードを使った複雑なスキーマは想定外になりやすい状態でした。2026-07-28版はこの制限を外し、$ref・anyOf・oneOf・allOfを含む2020-12の任意のキーワードを使えるようにしています。

スキーマの許容範囲とstructuredContentの変化

3つの変更点は次の表のとおりです。

structuredContentの変化は仕様書の一文そのものが書き換わっています。2025-11-25版は「structuredContentはJSONオブジェクトとして返される」と明記していました。2026-07-28版はこの一文を「任意のJSON値」に置き換えています。ユーザー一覧を返すツールの結果例で見ると次のようになります。

{
  "content": [{ "type": "text", "text": "Found 2 users: Alice and Bob." }],
  "structuredContent": [
    { "id": "1", "name": "Alice", "email": "alice@example.com" },
    { "id": "2", "name": "Bob", "email": "bob@example.com" }
  ]
}

配列そのものをstructuredContentに入れたこの結果は、2025-11-25版の文面どおりに読めば範囲外でした。2026-07-28版では正規の書き方です。

outputSchemaを宣言したツールには、型の許容範囲が広がった後も義務が変わらない部分があります。サーバーはoutputSchemaに適合する構造化結果を返さなければならず、クライアントはその結果をoutputSchemaと照合して検証すべきだという原則です。型が「オブジェクトのみ」から「任意のJSON値」に広がっても、宣言したスキーマとの整合性を取る責任そのものは両者に残ります。

既存のツール定義を書き直す必要があるかというと、方言を明示しているスキーマに限れば答えは「いいえ」です。$schemaフィールドでdraft-07など2020-12以外の方言を明示したスキーマは、2026-07-28版でも変わらず有効です。今回広がったのは、方言を省略したとき暗黙に前提とする2020-12スキーマが使えるキーワードの範囲であって、既存の明示的な方言指定を無効にする変更ではありません。

$refキーワードの解決に上限が必要になった理由

$refはJSON Schema 2020-12で絶対URIを指せます。仕様はここに新しい制約を課しました。実装は既定でネットワーク越しの$refを自動解決してはいけません。オプトインで解決する場合も、ホストの許可リストを用意するか、少なくともループバック・リンクローカル・プライベートアドレスへの参照を拒否し、タイムアウトとサイズ上限を設け、解決したURIをログに残す必要があります。

この要件が想定しているのは、悪意あるスキーマが検証器を通じて内部ネットワークへリクエストを送らせる攻撃です。ツール定義は外部のMCPサーバーから届く、信頼度の低い入力です。そこに含まれる$refをそのまま追いかけると、検証器自身がSSRF(サーバー側リクエスト偽造)の踏み台になります。

合成キーワード(anyOf・oneOf・allOf・if/then/else)と$defsにも、同じ理由で上限が課されました。これらは表現力の高いスキーマを書けますが、検証コストも跳ね上がります。仕様はスキーマの深さ・サブスキーマの総数・検証1回あたりの時間予算のいずれかに、妥当な上限を設けることを勧めています。上限がないと、悪意あるスキーマが検証器へのサービス拒否(DoS)攻撃として働く恐れがあるからです。

この2つの要件に共通するのは、仕様が具体的な数値でなく原則だけを定めている点です。深さの上限を「5」や「10」と指定するのではなく、「妥当な上限を設けよ」という判断を各実装に委ねています。MCPサーバーやクライアントを実装する側は、自分のスキーマ検証ライブラリがこの2つの要件をどう満たしているかを個別に確認する必要があります。

Claude CodeはMCPツールをどう検証しているか

Claude Codeは、MCPサーバーから受け取ったツール定義をClaude APIへ送る前に、独自の検証を挟んでいます。ここでの挙動は、SEP-2106が緩めた合成キーワードの扱いと直接つながっています。

まず合成キーワードです。Claude APIはスキーマのルート直下にあるanyOf・oneOf・allOfを受け付けません。ネストしたpropertiesの中にある合成キーワードはそのまま送信されます。ルート直下に合成キーワードを持つツールも、それだけで使えなくなるわけではありません。Claude Codeは送信前にスキーマを1つのオブジェクトへ平坦化し、パラメータの組み合わせをツールの説明文に追記します。allOfは各分岐のpropertiesとrequiredをすべて反映し、anyOf・oneOfはpropertiesをマージしたうえでrequiredの制約を説明文側に回す扱いです。

次にスキーマ全体の妥当性です。Claude Codeはv2.1.216以降、Claude APIが個別に課している2つのチェックを、ツール一覧を読み込んだ時点で自前でも実行します。1つはプロパティ名の文字種と長さで、トップレベルのプロパティ名はASCII文字・数字・_・.・-のみで1〜64文字という制約です。もう1つが、$schemaを省略したスキーマと2020-12を明示したスキーマを対象にした、2020-12メタスキーマへの適合チェックです。ここで失敗したツールは、そのサーバーの他のツールを道連れにせず、そのツール単体だけが除外されます。除外の理由はサーバーのログに記録され、Claudeにも「どのツールがなぜ除外されたか」が伝わる設計です。v2.1.195より前のバージョンは、ルート直下にanyOf・oneOf・allOfを持つツールを丸ごとスキップしていました。平坦化による救済が入ったのはそれ以降です。

MCPサーバー開発者が確認しておきたい3点

自分のMCPサーバーを2026-07-28版の仕様に合わせるなら、優先すべき確認は3つです。

• 合成キーワードの配置: ルート直下のanyOf/oneOf/allOfは、Claude Code経由だと平坦化されて説明文頼みの緩い制約になります。厳密さが要るならpropertiesの中に置く設計のほうが確実です
• structuredContentの型: クライアント側で常にオブジェクトとして扱うパーサーは、配列や文字列を返す新しいツールで壊れます。型を決め打ちしない実装にしておくと安全です
• $refの解決ポリシー: 仕様は既定で自動解決を禁止する立場です。外部URLへの$refを動的に解決する設計にしているなら、許可リストと拒否条件を自分のサーバー側で明文化しておきます

構造化出力コマンドとの違い(--json-schema)

ここまでのJSON Schema 2020-12は、MCPのツール定義の話です。Claude Codeのclaude -p --json-schemaが検証するJSON Schemaとは別物です。

--json-schemaはClaudeの応答そのものを指定した構造に固定する、Agent SDKの構造化出力機能です。この検証はdraft-07を対象にしており、Zodなど2020-12を既定出力するライブラリからスキーマを生成する場合はtarget: "draft-7"の明示が必要になります。エラーメッセージや挙動の詳細はClaude Code --json-schemaエラーの直し方にまとめてあります。MCPのツール定義側とAgent SDKの構造化出力側で、2つの別々のJSON Schema検証が同じCLIの中に存在しています。

まとめ

2026-07-28版のMCP仕様は、ツール定義のJSON Schemaが使えるキーワードを広げ、structuredContentをオブジェクト限定から解放しました。一方で$ref解決と合成キーワードの計算量には、新しい安全要件が課されています。仕様書はこの安全要件を具体的な数値でなく原則で定めており、実装側の裁量に委ねられた範囲が広い変更です。

MCPサーバーを自作している場合は、ルート直下の合成キーワード・structuredContentの型・$refの解決ポリシーの3点を確認すると、この改定への追随が完了します。サーバーを自作する手順はMCPサーバー自作ガイド、同じ2026-07-28版で変わったOAuth認可の側面はリモートMCPのOAuth認証で扱っています。