私たちはMCPサーバーを間違って作っている

ほとんどの開発者が最初のMCPサーバーを構築するとき、予測可能なことをする：REST APIを取り、各エンドポイントをMCPツールとしてラップする。GET /usersはget_usersツールになる。マッピングは1:1で、機械的で、間違っている。

間違っている理由は、REST APIがドキュメントを読み、データモデルを理解し、複数の呼び出しを頭の中で連鎖させられる開発者のために設計されているからだ。LLMはそうは動かない。ドキュメントではなくツールの説明で動く。

RESTを盲目的にMCPにマッピングすると、LLMにAPIドキュメントが人間の開発者に与えたであろうメンタルモデルを再構築させることになる。

根本的な思考の転換はこうだ：RESTエンドポイントはリソースをモデル化する。MCPツールはタスクをモデル化すべきだ。

REST APIにはGET /users/{id}、GET /users/{id}/orders、GET /orders/{id}/itemsがある。3つのエンドポイント、3つの呼び出し、3つの応答。

MCPサーバーにはget_user_order_summaryツールがあるべきだ。LLMは「このユーザーは何を注文した？」と聞いた——3つのパズルピースではなく、答えを与えよ。

API純粋主義者にはおかしく感じるだろう。正規化に違反する。しかし消費者はクリーンなコードを書く開発者ではない——より少なく、より完全なツール呼び出しでより良く機能するLLMだ。

REST APIでは、エンドポイントパスとHTTPメソッドがセマンティック情報を運ぶ。GET /usersは自明だ。

LLMはURLパターンを解析しない。ツールの説明を読む。ツールの説明が唯一重要なドキュメントだ。曖昧なら、LLMはツールを間違って使う。

システムについてコンテキストを持たない非常に文字通りに解釈する同僚にツールを説明するように書け。ツールが何をするか、何を返すか、いつ使うべきか、いつ使うべきでないかを正確に言え。

ほとんどのMCPサーバーの説明は、テクニカルライティングの授業ならD評価だ。これが最もレバレッジの高い改善だ。

常に見るパターン：search_documents、find_documents、query_documentsを持つMCPサーバー。ほぼ同じことをする3つのツール。

人間の開発者には違いは明白だ。LLMにとっては、似た説明の3つのツールで、どれを使うか推測しなければならない。約40%の確率で間違える。

ツールの重複はMCP信頼性問題の最大の原因だ。解決策は容赦ない重複排除。2つのツールが統合できるなら統合せよ。ツールを追加する代わりにパラメータを追加せよ。

少なくて有能なツールは常に多くの専門ツールに勝つ。

メタレッスンはシンプルだ：MCPツールはREST APIとは異なる消費者を持ち、異なる消費者には異なるデザインが必要だ。

実際のLLMでツールをテストせよ。「ツールは正しく実行されるか」だけでなく——「LLMは正しいツールを選び、正しいパラメータを渡し、応答を正しく解釈するか？」

本番でLLMが実際にツールをどう使うか監視せよ。驚くパターンが見つかるだろう。

最高のMCPサーバーは最も多くのツールを持つものではない。LLMが毎回最初の試みで正しい答えを得るものだ。それが唯一重要な指標だ。