【2026年版】Claude CodeのMCPサーバー自作ガイド｜AIを迷わせないツール設計の完全攻略

Claude Codeの機能を拡張するMCPサーバーの自作は、AIエージェントをただのチャットボットから真のエンジニアへと進化させる鍵だ。この記事では、AIを迷わせないためのツール設計と、実用的なMCPサーバーを構築するためのベストプラクティスを解説する。AIコーディング環境を効率化する手法を学ぶ。

SNS運用を自動化しませんか？

ThreadPostなら、投稿作成・画像生成・スケジュール管理までAIがサポート。

無料で始める

MCPサーバーの配置と命名規則の鉄則

MCPサーバーを自作する際、最初に直面する壁はファイル配置だ。Claude Codeのプラグインは、プロジェクト直下の「.claude-plugin/」ディレクトリに配置する必要がある。設定ファイル名である「plugin.json」や「mcp.json」の先頭にドットを忘れると、検証ツールでエラーが出ないまま読み込まれないという罠がある。

配置場所を間違えると、AIはツールを一切認識しない。設定ファイル名は「.claude-plugin/」内であればドットなしで問題ないが、ディレクトリ構成自体を隠しフォルダにする必要がある。この命名規則の厳守が、プラグイン開発の最初の関門だ。

Capabilityによる機能のモジュール化

Pydantic AI v2の「Capability」のように、命令文・ツール・フック・設定を1つのオブジェクトにまとめる設計思想を取り入れる。機能を増やすたびに複数のファイルを修正するのではなく、機能単位でカプセル化することで、管理コストを下げ、再利用性を高めることが可能だ。

機能をモジュール化すると、将来的な拡張がリストへの追加だけで完結する。AIエージェントのコード構造を整理し、機能の差し替えを容易にするこの手法は、長期的な開発において強力だ。

巨大データの検索最適化

巨大なSwaggerやドキュメントをそのままAIに渡すと、AIはトークンを浪費し、迷子になる。「タグ一覧」→「エンドポイント一覧」→「詳細取得」という3段構えのツール設計が有効だ。

検索にはMiniSearch等のインデックスを活用し、必要な情報だけを抽出する仕組みを構築する。全文を読み込ませるのではなく、メモリ上のインデックスを引くことで、回答精度を維持しつつトークン消費を最小限に抑えることができる。

エージェントを迷わせないツール命名と説明

ツールが増えると、AIは適切な選択ができなくなる。人間にとっての分かりやすさより「AIが区別できる名前」を優先する。Descriptionには「何に使い、何に使わないか」を明記することが不可欠だ。

曖昧さを排除し、ツールの役割を明確に定義することで、エージェントの自律性は向上する。人間が読みやすい名前よりも、AIが迷わない名前を選ぶのがプロの設計だ。

しんたろー：
Claude Codeでコードを書く際、ツールの説明文に「Do not use for」を書くのが効果的だ。曖昧な名前のツールを減らすだけで、AIの推論ミスは激減する。

ここまで読んだあなたに

今なら無料で全機能をお試しいただけます。設定後はAIが投稿案を毎日生成。確認して選ぶだけ。

無料で始める

パラメータの型定義と制約の厳格化

曖昧なパラメータはAIの失敗を招く。文字列型で渡すのではなく、列挙型（enum）で選択肢を限定したり、ISO 8601形式などの期待するフォーマットを明示的に記述する。

API呼び出し時のエラーを未然に防ぐため、バリデーションを厳密に実装する。エージェントがパラメータ入力に迷う時間を減らすことが、全体の作業速度を上げる。

ツール利用の依存関係の明確化

ツールAの結果をツールBに渡すような依存関係がある場合、Descriptionにその手順を明記する。AIに「IDが必要なら先にこのツールを呼べ」と指示することで、推論プロセスを誘導し、迷子になるのを防ぐことができる。

設計項目	良い例	悪い例
ツール命名	search_internal_docs	search
説明文	Do not use for public info	検索する
パラメータ	ISO 8601形式の日付	適当な日付文字列
依存関係	最初にID取得ツールを呼ぶ	ツールを単発で使う

しんたろー：
複雑なワークフローをAIに任せるなら、依存関係の明示は必須だ。MCPサーバーを作る際、常に「AIが次に何をすべきか」をDescriptionに書き込むのが定石だ。

FAQ

Q1: MCPサーバーを作ったのにClaude Codeが認識してくれません。

A1: 主な原因は配置場所と命名規則だ。必ずプロジェクト直下の「.claude-plugin/」ディレクトリに配置し、設定ファイル名が「plugin.json」や「mcp.json」のように、先頭にドットが付いていないか確認する。また、公式の検証コマンドを実行し、エラーが出ていないか確認することが重要だ。

Q2: ツールを増やしたらAIが変なツールばかり選ぶようになりました。

A2: ツール名が似通っているか、Descriptionが不足している可能性が高い。AIは名前と説明文だけで判断するため、「検索」という曖昧な名前ではなく「search_internal_docs」のように対象を明示し、説明文には「何に使い、何に使わないか」を具体的に書き足すと改善する。

Q3: 巨大なAPI仕様書をAIに読ませたいのですが、どうすればいいですか？

A3: 全文を一度に渡すのは避けるべきだ。必要な部分だけを抽出する「検索用MCP」を自作する。起動時に一度だけJSONをメモリに読み込み、インデックス化する。AIからは「list_tags」「get_endpoint_detail」のようなツール経由で、必要な箇所だけをピンポイントで取得させるのが正解だ。

Q4: ツールに渡すパラメータでAIがよく失敗します。

A4: パラメータの制約を厳しく定義する。例えば「environment」という引数なら、単なる文字列ではなく「production, staging, development」のいずれかであることをDescriptionに明記する。日付形式なども「ISO 8601形式で入力せよ」と指示することで、API側のエラーを減らせる。

Q5: 初心者が最初に作るべきMCPサーバーは何ですか？

A5: 「社内ドキュメント検索」や「特定のAPI仕様の検索」がおすすめだ。これらは「検索→結果表示」というシンプルなフローで完結するため、MCPの基本構造を学ぶのに最適だ。まずは複雑な書き込み処理などは避け、読み取り専用のツールから作り始めるのが成功の秘訣だ。