約 3 分で読めます

MCPのJSON Schema方言ずれを検出する契約テスト

MCPコントラクトテストスキーマドリフト

ツール定義の inputSchema は、サーバー側では通ったのにクライアント側で拒否される。あるいは拒否されず、不正な引数がそのまま通る。原因がモデルでもネットワークでもなく、スキーマの「方言」である場合、ログを眺めても手がかりは出てきません。MCPでは方言の扱いが仕様で定められているため、ずれは仕様に沿った最小反例で機械的に検出できます。なお、ツール定義そのものの変化を追う手法はスキーマドリフトの契約テストで扱っています。本記事は「同じ定義を、双方が同じ意味で解釈しているか」の検証に絞ります。

MCPのJSON Schemaは何を既定の方言とするのか

$schema を省略したスキーマは JSON Schema 2020-12 として扱うのがMCP仕様の既定です。別方言は $schema で明示できます。

2025-11-25版の仕様(Basic > JSON Schema Usage)は次のように定めています。

  • $schema がない場合の既定方言は 2020-12
  • 実装は少なくとも 2020-12 をサポートしなければならず(MUST)、追加でサポートする方言は文書化すべき(SHOULD)
  • 宣言された方言(または既定)に従って検証し、未対応の方言は適切なエラーで返す
  • スキーマ自体が、宣言または既定の方言に対して妥当であること

この既定は SEP-1613 で確立されました。動機として、実装が draft-07 と 2020-12 に割れており、クライアントとサーバーが異なる版を前提に検証失敗を起こしていた点が挙げられています。本記事は2025-11-25版を固定の根拠としており、これが最新仕様だと断定するものではありません。採用する版は自社の実装時点で再確認してください。

方言ずれはどこで壊れるのか

壊れ方は2通りです。方言を拒否して接続自体が失敗するか、未知のキーワードを黙って無視して検証が素通りするかです。

後者のほうが危険です。JSON Schema では未知のキーワードは無視されるのが基本のため、方言を取り違えると「エラーなしで制約が効かない」状態になります。SEP-1613 が移行注意として挙げているのは次の2点です。

  1. dependencies は dependentSchemas と dependentRequired に分離された
  2. 位置指定の配列検証は prefixItems に移った

2020-12 のリリースノートによれば、prefixItems が旧 items(配列形式)の役割を引き継ぎ、新しい items は旧 additionalItems に相当します。閉じたタプルは prefixItems に "items": false を併記して表します。再帰参照も $recursiveRef から $dynamicRef に置き換わりました。

最小反例で方言を判別するテストはどう書くか

方言ごとに結果が分かれる最小スキーマと入力の組を固定し、期待する合否を契約として持ちます。

次の反例は、方言の解釈が結果に直結します。

{
  "case": "tuple-prefixItems",
  "schema": {
    "type": "array",
    "prefixItems": [{ "type": "string" }, { "type": "integer" }],
    "items": false
  },
  "valid": [["a", 1]],
  "invalid": [[1, "a"], ["a", 1, true]]
}

2020-12 として解釈すれば invalid の2件は拒否されます。prefixItems を知らない draft-07 系の検証器では、items: false と組み合わさって挙動が変わるため、ここで差が表面化します。旧形式(items に配列を渡す)のケースも並べ、2020-12 ではスキーマ自体が不正になることを確認します。

テストケースは次の観点で用意します。

  • $schema 未指定、2020-12 明示、draft-07 明示の3系統で同じ入力を流す
  • prefixItems / dependentRequired / $dynamicRef を各1ケース
  • 外部 $ref を含むスキーマ(解決の可否と、解決先の方言)

クライアントとサーバーの双方をどうCIに組み込むか

サーバーは自分が公開する定義を、クライアントは受け取る定義を、それぞれ同じ反例集で検証します。

反例集を単一のフィクスチャとして管理し、両側から同じファイルを読みます。

  1. サーバーCI: tools/list の全ツールについて、inputSchema / outputSchema が宣言(または既定)の方言に対しメタスキーマ妥当であることを検証する
  2. クライアントCI: 反例集を使い、採用SDKの検証器が方言ごとに期待どおり合否を返すことを検証する。未対応方言でエラーが返ることも確認する
  3. 検証器の設定(既定方言、外部 $ref の解決可否、メタスキーマの登録有無)をテストの前提として固定し、SDK更新時に差分が出たら失敗させる

方言を宣言しない場合の既定はクライアント実装側にも依存します。SDKが出力する方言と、接続先クライアントが期待する方言が異なる事例はコミュニティの報告にも見られるため、「$schema を明示して出力する」ことをサーバー側の既定ルールにするのが安全です。

規模別の留意点(SMB / エンタープライズ)

SMBでは、利用するSDKとクライアントの組み合わせが少ないため、反例集は5〜10件で足ります。導入するMCPサーバーの受け入れ時に1回流す運用から始められます。伴走支援はAI導入・定着支援が対応します。

エンタープライズでは、社内で複数チームが異なるSDK版でサーバーを公開します。反例集と検証器設定を共通基盤として配布し、ゲートウェイ登録時の必須チェックにします。全社規模の統制設計はRDEの対象領域です。

参考

まとめ

MCPの方言ずれは、最小反例とメタスキーマ検証をCIに置けば検出できます。$schema の明示が最初の一手です。

要点は3つです。既定方言は2020-12であること、方言ずれは「拒否」より「素通り」が危険であること、反例集をクライアントとサーバーで共有することです。

MCP基盤の受け入れテストや統制設計でお困りの場合は、Kuu株式会社にご相談ください。

関連記事

MCPクライアントのiss検証とissuer紐付け実装MCPキャッシュ設計——ttlMsとcacheScopeの決め方x-mcp-header設計——引数をHTTPヘッダーで制御するMCPのページネーション設計——cursorの正しい扱い方