私はゲームをしながらの一晩で、SirenのMCPサーバーであるBeaconの最初に動くバージョンを作り上げました。
その夜に出荷したものは、技術的には機能するMCPサーバーでしたが、完全に使い物になりませんでした。Claudeはツールを見られます。Claudeはツールを一覧できます。Claudeは毎回自信満々に間違ったツールを選び、実在しないものに合わないパラメータでそれを呼び出し、その後は何が起きたかについてユーザーに気持ちよく嘘をつきます。私は、非常に高価な乱数生成器を作って、それを自分のAPIに取り付けただけでした。
分かったのは、MCPサーバーはREST APIとは別物だということ、そして私はまさにその理由を学んでいる最中だった、ということです。
MCP !== REST
私が最初に抱いていた前提はこちらです。REST APIがある。MCPツールは単にエージェントが呼び出せる「何か」です。だから、RESTエンドポイントごとにMCPツールは1つ、ですよね？そうですよね？ Sirenには大量のエンドポイントがあるので、Beaconは初日から30〜40程度のツールを搭載して出荷しました。あらゆるCRUD操作。あらゆる特化した検索。あらゆる一覧のバリエーション。全部です。露出させました。
それは常に幻覚を起こし、間違ったツールを選び、正直なところ動いていませんでした。
まだ理解できていなかったのは、MCPツールの「表面」はAPIではない、という点です。モデルが毎ターン読むメニューなんです。メニューに項目が増えるほど、ツール説明に使われるトークンが増えます。モデルが選ぶための、ほぼ同じ選択肢が増えます。そして、ほぼ正しいものを掴んでしまうチャンスが増えます。
AIエージェント側の体験は、私が初めてBlenderを開いたときに自分の身に起きたことと似ていると思います。私は長年CADを使ってきましたが、Blenderは使ったことがありませんでした。3Dモデリングのことは知っていて、概念も理解していました。でも、あまりにも見慣れないツールの壁を見つめると、それらがすべて少しずつ違うことをするように見えて圧倒され、タスクを終えるために何を選べばいいのかまったく分かりませんでした。
それが、モデル側から見たときに大きすぎるサーフェスのMCPサーバーがどんなものか、だいたいそんな感じです。
REST APIは、ドキュメントを読める開発者向けで、データモデルを頭の中で保持できていて、たとえ両方とも技術的には動くとしても、GET /programs/{id}/distributorsとGET /distributors?program_id={id}が違うことを知っています。モデルにはその文脈がありません。メニューから選んでいて、そのメニューこそが世界のすべてなんです。
The fix: fewer tools, aggressive parameterization
最初のバージョンが私の前であまりにも何度も恥をかかせてくれたあと、私は調査しました。パターンは何度も何度も出てきます。実際に本番で使われているMCPは、小さいサーフェスを持っている、ということです。驚くほど小さい。
そこで全体を作り直しました。Beaconにはツールが3つ、数え方によっては4つです。私が日常的に実際に使っている他のMCPも、同じようにツール数がとても少ない。それは偶然ではありません。これがパターンです。
バリエーションごとに別ツールを作るのではなく、積極的にパラメータ化するのが方針です。検索ツール1つにcontentTypeパラメータを持たせる。コンテンツタイプごとに検索ツールを6つ作るのではありません。IDのリストを受け取る取得ツールを1つにする。リソース種別ごとに1つずつ作るのではありません。このツールは、あなたのエンドポイント一覧の1行に対応しません。ユーザーが実際に口にしそうな動詞に対応します。
動詞だけではありません。データの返り方もです。レスポンスでエージェントが欲しがる「型」や「フィールド」をパラメータ化することで（GraphQLがそうであるのと同様に）、トークン効率の高いリクエストとレスポンスのサイクルを組み立てられるようにします。必要なものだけを返し、それ以上は返さないようにする。そうすればトークン代を節約できますし、コンテキストウィンドウの圧力が積み重なるような長い会話でも、エージェントの信頼性が上がります。
違いは文字通り昼と夜でした。以前は、私はMCPサーバーをセットアップし、設定までしていたのに、私が向けたあらゆる看板級エージェントに完全に無視されていました。後は、自分の仕事で毎日使うものが手に入りました。正直なところ、私が適用できる最高のハードルを満たしたものです。
今私がツールを追加しそうになったときに使っているテストはこれです。既存のツールにパラメータを追加することで同じ挙動が得られるでしょうか？Yesなら、そのパラメータを追加します。ほとんどの場合、追加できます。
Why this is so easy to get wrong
賢い人たちが40ツールのMCPサーバーを作り続ける理由は、どのツールも、単体で見ると必ず正当化できてしまうからです。「パラメータが違うから、この特定の検索用にツールが必要だ」「レスポンスの形が違うから、ここは別ツールが必要だ」「これは読み取り専用で、あれは書き込みだから、これは分ける必要がある」——。それぞれの判断は局所的です。それぞれの判断は弁護できます。結果として、最初にホワイトボードで描いていたら誰も意図して設計しなかったようなサーフェスになってしまいます。
あなたを壊すのは、どれか1つのツールではありません。メニュー全体の形です。
もし私が制約「3つのツールで、すべてを収める」を最初に課していたら、初日からパラメータについてまったく違う選択をしていたでしょう。なので私は、新しいMCPを始めるときは、今でもこのメンタルモデルで考えています。まず動詞を選ぶ。全部をそれらに押し込む。本当に分割が避けられないときだけ分ける（分けると判断したときは、自分に対して疑い深くなるべきです）。
Connecting your MCP to web agents
最大の技術的課題は、ツール設計ではありませんでした。OAuthでした。
私は最近、すべてをPHPNomadで書いています。私はWordPressの内外の両方で仕事をしているので、最初から、私のMCPシステムはどちらの文脈でも使えるスタック上に置きたくて、考えていました。PHPNomadはそれを可能にするために私が作ったフレームワークで、Beaconは最初からそれの上に作ることになるはずでした。Nomadicとは、同じコアロジックがマイクロサービスやWordPressプラグイン、その他PHPがホストできる何かとして動くことを意味し、書き直さずに済むんです。
良い点はそれです。大変な点は、Beaconを始めたときのPHPNomadにはOAuthサポートがなかったことなので、自分で調べて自前のフローを組み立て、作らなければならなかった、ということです。それには本当に手間がかかりました。そして、それは避けられないものでした。Claudeや他の主要級エージェントは、接続のためにOAuthフローが必要だからです。OAuthがなければ、本番のMCPもない。見込み客がURLをClaudeに貼り付けてSirenと話し始めるような販売会話もありません。
正直に言うと、もしあなたがすでにOAuthフローの構築に慣れていないなら、別のスタックを検討してください。OAuthは週末プロジェクトではありません。セキュリティ境界であり、間違った実装は本当のトラフィックを扱うまで表に出ない形であなたを痛めつけます。私は自分で作りました。PHPNomadを前に進めるために必要だったことと、キャリアを通してGoDaddyのような場所でいくつかのOAuthシステムを作ってきたからです。そういう経験がツールベルトにないなら、OAuthがすでに動くスタックを選び、重い作業は他の誰かに任せましょう。
PHPNomadには今OAuthがあります。つまり、それの上に構築する次のMCPは、出荷コストが劇的に下がるということです。インフラのコストを一度だけ払い、その後はずっと無料で使えます。
Save yourself the heartache: don't test with voice mode
最後にもう一つ、できれば誰かが私に言ってくれていたらよかった話です。Web上のほとんどのAIエージェントにおけるボイスモードは、UIがそう言っていて、エージェント自身が見えていると思っていても、実際にはあなたのMCPツールを使いません。できません。ボイスインターフェースは、現時点（あなたのことです、主要ベンダーの全員）ではMCPサーフェスの一部のみに対してのみ動作します。
なので、MCPを設定し終えたら、それを話しかけて試したくなる衝動に抵抗してください。まずは通常のテキストインターフェースで試してください。ツールが実際に呼び出されることを確認します。エージェントがパラメータを正しく読み取っていることを確認します。その後でボイスモードを有効にして、あなたのサーフェスのどれだけが生き残るかを見てください。
どうやって分かったのか、聞いてください。
The lesson, compressed
MCPサーバーをこれから出荷しようとしている、またはすでに出荷したのにうまく動いていない場合、問題は「どんなシステムプロンプトが必要か？」ではありません。「どれだけのツールを公開しているか、そしてその数を90%減らしたらどうなるか？」です。
Beaconは、動かなかった30〜40のツールから、毎日使う3〜4のツールへと変わりました。プロダクトは変わっていません。APIも変わっていません。モデルに公開したサーフェス（接触面）が変わっただけで、それがすべてでした。
Sirenの上に構築していて、小さなサーフェスのパターンを実際に見たいなら、Beaconは稼働中です。接続して、いじってみて、ツールの説明を読んでください。大きなファイルではありません。そこがポイントです。
