MCPツールと応答仕様

法レンズのMCPサーバを利用する開発者・研究者向けに、エンドポイント、ツールの入出力、応答形式、エラーハンドリングを解説します。AIエージェントからも参照できる技術資料です。

設計方針と評価の記録は研究ページにあります。ここでは、クライアントが利用するインターフェース仕様を扱います。接続の手順は接続ガイドにあります。

エンドポイントとOAuth認証

MCPサーバには2つのエンドポイントがあります。資料と検索・取得処理は共通です。AIに提示するツールと、接続時の案内が異なります。

既定のエンドポイント

POST https://houlens.jp/api/mcp。MCPの仕様に沿って動くクライアント（Claudeなど）向けです。用途ごとのツールを掲載しています。

OpenAI向けのエンドポイント

POST https://houlens.jp/api/mcp/openai。ChatGPT・Codex向けです。用途別のツールに加えて、候補を探す search と本文を取得する fetch を一覧に出します。

認証

OAuthの認可コードフローとPKCEのS256を使います。スコープはmcpで、クライアントシークレットは発行しません。両方のエンドポイントで認証は共通です。アカウントの利用条件と登録方法は、接続ガイドにまとめています。

エンドポイントごとの保護リソースメタデータは、/.well-known/oauth-protected-resource/api/mcpと/.well-known/oauth-protected-resource/api/mcp/openaiです。認可サーバの情報は/.well-known/oauth-authorization-serverで取得します。

Codexの案内は既存の接続手順を参照してください。既定のエンドポイントではsearchとfetchを一覧に載せませんが、呼び出し自体を禁止しているわけではありません。

MCPツール一覧

すべてのツールは読み取り専用です。資料の作成・変更・削除は行いません。検索候補と原文を提供し、法律上の判断や助言は示しません。

用途別のツールと主な入出力
ツール	役割	主な入力	主な出力
`search_cases`	判例を検索する	自然言語クエリまたはキーワード。検索モード（意味検索・キーワード検索・ハイブリッド検索）と、裁判所の種別や条文での絞り込み	書誌情報と抜粋、検索方式ごとのスコア。意味検索では条件に応じて最上位結果とのスコア比率とconfidence
`get_case`	判例の書誌情報と本文の状態を取得する	判例ID	書誌情報、本文の有無と総字数、判決文のセクションの一覧、原本への案内、原審の情報（ある判例のみ）
`read_case_text`	判決文を読む	判例IDと、セクションの指定または位置の指定	指定した範囲の本文と、次の範囲を読むための指定
`find_in_case`	判決文の中で語句を探す	判例IDと、2字以上100字以内の文字列	一致した位置、前後の抜粋、一致を含むセクション
`read_original_page`	原本PDFのページ画像を取得する	判例IDと、ページの指定	ページの画像と、そのページから抽出したテキスト
`get_similar_cases`	類似判例を検索する	起点にする判例ID	類似した判例と、似ている箇所の抜粋
`lookup_case_citation`	事件番号で判例を照合する	事件番号（表記の揺れは吸収する）	一致した判例と、一致した事件番号の種別
`resolve_law_name`	法令名の候補を取得する	法令名、略称、旧題名	正式な法令名、法令番号、法令IDの候補
`get_statute`	条文を取得する	法令名・法令ID・法令番号のいずれかと、条と、基準日	指定した基準日に対応する条文、または候補・取得できない理由。版の注記も返す
`list_statute_articles`	条の見出しを一覧する	法令の指定と、基準日	条の見出しと並び、条の削除フラグ
`compare_statute_revisions`	改正の前後で条文を比べる	法令と条と、2つの基準日	前後の条文と、行単位の差分
`search_statutes`	条文を検索する	自然言語クエリ	条の候補と、一致した項の抜粋
`search_cases_and_statutes`	判例と条文を同時に検索する	自然言語クエリ	判例の候補と条文の候補（スコアは別々に返す）
`get_coverage`	収録範囲を確かめる	なし	判例の収録件数と内訳、条文の収録と同期の状態
`search`	候補を探す（OpenAI向けの一覧に掲載）	自然言語クエリまたはキーワード	候補のID、表題、抜粋、原本ページのURL、類似度スコア
`fetch`	本文を取得する（OpenAI向けの一覧に掲載）	searchが返したID	書誌情報と判決文の本文。続きはIDの指定で読み進められる

各ツールの定義には、入出力の項目名と型を宣言したスキーマが付きます。引数は、そのスキーマと説明文で確認できます。

応答形式

JSONのオブジェクトを返す成功応答には、structuredContentと、同じ内容をJSON文字列にしたcontentが入ります。ツールエラーは別の形式です。read_original_pageの応答には画像コンテンツも含まれます。

検索方式で変わる項目

search_casesのscoreは検索方式ごとのスコアです。意味検索ではconfidenceの区分と、スコアが正の場合にscore_ratio_to_topが付きます。比率は順位を読むための値で、回答の正しさや法的な確度を表しません。

alertsは応答に付随する注意事項を示します。codeとmessageに加え、関係する項目があるときはfieldが付きます。意味検索で結果間のスコア比率が近接している場合にはscore_ratio_narrowが入ります。

JSONsearch_cases · 意味検索

structuredContentの抜粋 / 資料の値は架空

{
  "results": [
    {
      "case_id": "example-case",
      "court": "説明用の裁判所",
      "date": "2020-01-01",
      "case_number": "説明用の事件番号",
      "excerpt": "説明用の抜粋。実在の判決文ではありません。",
      "score": 0.82,
      "score_ratio_to_top": 1,
      "confidence": "high",
      "source": "courts_web"
    }
  ]
}

この例はsearch_casesへmode: semanticを指定した場合の一部です。標準のsearchはid・title・text・url・scoreを返します。標準のsearchには、比率やalertsは付きません。

次に試す操作

next_actionsがある場合、各案のtoolとargumentsを次の呼び出しに使えます。reasonで理由を確認してください。案が空の場合もあり、再検索で結果が見つかる保証ではありません。

資料の取得元

判例のsourceは出所の区分です。判例テキストに添えるprovenance.authoritative: falseは、原本から抽出したテキストが原本そのものではないことを示します。引用する際は原本を確認してください。

条文のsourceは取得元と加工の説明です。条文DBから読んだ場合と、DBにない版をe-Gov法令APIから取得した場合を区別します。last_synced_dateはDB由来の応答に付き、APIから直接取得した応答には付きません。

結果の解釈とエラー処理

検索が0件でも、呼び出し自体は成功です。標準のsearchは空のresultsにnoteとprovenanceを添えます。search_casesでは条件に応じたnext_actionsも返りますが、案が空の場合があります。

JSONsearch · 検索が0件

structuredContentの抜粋 / noteとprovenanceは省略

{
  "results": []
}

ツールを実行した結果のエラーは、HTTP 200のJSON-RPC応答のresultにisError: trueを付けて返します。この場合はstructuredContentを付けず、contentのテキストで理由を伝えます。

JSONsearch · queryを省略

tools/callのresult / 入力エラーの応答

{
  "content": [
    {
      "type": "text",
      "text": "query は必須です。検索したい内容を質問文またはキーワードで渡してください。"
    }
  ],
  "isError": true
}

ツールの結果に応じた確認
結果	意味	次にできること
検索が0件	指定した条件で候補が見つからなかった結果です。資料の不存在や未収録を確定するものではありません。	noteと収録範囲を確認します。next_actionsがある場合は、その引数と理由を読み、条件を変えて再検索できます。案が空のこともあります。
事件番号で照合できない	番号の表記や書誌情報の不足によって、一致を検出できない場合もあります。	裁判所名と言渡日を確認します。実行できる再照合案がnext_actionsにあれば利用し、それでも特定できなければ未確認と伝えます。
条文が削除済み	is_deleted: trueは、その版で条が削除されていることを示すフラグです。textを返す形式では削除の表記が入ります。	必要な基準日を確認します。過去の条文が必要なら、その日をreference_dateへ指定します。削除を取得障害とは扱いません。
指定した版が得られない	条を指定した場合はtext: null、指定しなければoverview: nullで返ります。公布前と履歴不足はstatusで区別します。	status、revision、noteを読み、取得できる最古の日付が示されていれば確認します。別の版を求めた日の条文として代用しません。
法令名の解決が曖昧	kind: law_ambiguousとcandidatesが返ります。法令を一つに決めて本文を返した状態ではありません。	候補の正式名称と法令番号を確認し、目的のlaw_idを使って再取得します。必要ならresolve_law_nameで候補を探します。
ツールが実行できない	入力不正、法令や条が見つからない場合、処理の障害などはisError: trueとテキストで返ります。	返された文に従って入力や再試行の可否を確認します。利用プランによるアクセス制限のメッセージは接続先で異なり、OpenAI向けにはプラン名や変更案内を含めません。

HTTP・JSON-RPC層のエラー

HTTPの認証・基盤エラーはツール結果とは別です。認証できない場合は401とWWW-Authenticate、本人状態やトークン検証記録などを読めない場合は503とRetry-Afterが返ります。503は資格情報の無効を示しません。指定の時間を待って再試行します。

レート制限の429や、リクエストの形式・未知のツールなどに対するJSON-RPCエラーも区別します。HTTPステータスとヘッダー、JSON-RPCのerror、ツール結果のisErrorの順に確認します。

応答の文に稼働状況の案内がある場合は、ステータスページも確認してください。案内が付かない一時的な失敗もあります。

収録範囲の確認

get_coverageで収録範囲を取得できます。判例の収録件数、裁判所の種別ごとの内訳、言渡日の範囲、条文の収録と同期の状態を返します。検索で見つからないことは、その資料が存在しないことを意味しません。見つからなかった範囲を伝えるときは、このツールの応答を根拠にできます。

収録範囲と注意事項の全体は、トップページの収録範囲にまとめています。このページでは繰り返しません。