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

> MCPのJSON Schemaは$schema未指定なら2020-12扱いです。draft-07との方言ずれを最小反例で検出し、クライアントとサーバーの双方でCIに組み込む手順を解説します。

- Canonical: https://kuucorp.com/blog/mcp-json-schema-dialect-compatibility-tests/
- Date: 2026-11-12
- Last modified: 2026-11-12
- Publisher: Kuu株式会社 (https://kuucorp.com)

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

## 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` に置き換わりました。

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

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

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

```json
{
  "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導入・定着支援](https://kuucorp.com/services/ai-ops/)が対応します。

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

## 参考

- [MCP Specification 2025-11-25: Base Protocol（JSON Schema Usage）](https://modelcontextprotocol.io/specification/2025-11-25/basic)
- [SEP-1613: Establish JSON Schema 2020-12 as Default Dialect for MCP](https://modelcontextprotocol.io/seps/1613-establish-json-schema-2020-12-as-default-dialect-f)
- [JSON Schema 2020-12 Release Notes](https://json-schema.org/draft/2020-12/release-notes)

## まとめ

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

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

MCP基盤の受け入れテストや統制設計でお困りの場合は、[Kuu株式会社](https://kuucorp.com/services/ai-ops/)にご相談ください。
