Claude Agent SDK で複数 MCP サーバを束ねるときのツール名衝突 — 名前空間と動的調停の設計

TypeScript で衝突調停器を実装する

ここからが実装です。複数の MCP サーバから取得したツール一覧を入力として、衝突を検出してリネームし、双方向の alias map を返す Reconciler を TypeScript で組みます。

// reconciler.ts
import type { Tool } from "@anthropic-ai/sdk/resources/messages.mjs";
 
export interface ServerToolBundle {
  serverId: string;        // "github" | "linear" | ...
  tools: Tool[];
}
 
export interface ReconciledTools {
  tools: Tool[];                                  // モデルに渡す最終形
  forward: Map<string, { serverId: string; original: string }>;
  reverse: Map<string, string>;                    // serverId:original -> renamed
}
 
const PREFIX_SEP = "__";
const NAME_RE = /^[a-zA-Z0-9_-]{1,64}$/;
 
export function reconcile(bundles: ServerToolBundle[]): ReconciledTools {
  const seen = new Map<string, string[]>();        // name -> [serverIds]
  for (const b of bundles) {
    for (const t of b.tools) {
      const list = seen.get(t.name) ?? [];
      list.push(b.serverId);
      seen.set(t.name, list);
    }
  }
 
  const conflictedNames = new Set(
    [...seen.entries()].filter(([, ids]) => ids.length > 1).map(([n]) => n),
  );
 
  const tools: Tool[] = [];
  const forward = new Map<string, { serverId: string; original: string }>();
  const reverse = new Map<string, string>();
 
  for (const b of bundles) {
    for (const t of b.tools) {
      const needsPrefix = conflictedNames.has(t.name);
      const renamed = needsPrefix ? `${b.serverId}${PREFIX_SEP}${t.name}` : t.name;
      if (!NAME_RE.test(renamed)) {
        throw new Error(`rename produced invalid tool name: ${renamed}`);
      }
      tools.push({ ...t, name: renamed });
      forward.set(renamed, { serverId: b.serverId, original: t.name });
      reverse.set(`${b.serverId}:${t.original ?? t.name}`, renamed);
    }
  }
  return { tools, forward, reverse };
}

ポイントは 3 つあります。第 1 に、衝突しているツール名だけをプレフィックス付けの対象にしています。第 2 に、forward と reverse の双方向マップを作ることで、モデルが github__create_issue を呼んだときに「GitHub サーバの create_issue を起動する」という逆引きが O(1) で済みます。第 3 に、リネーム後の名前を正規表現で検証して、Anthropic 仕様外の文字が混入したらビルド時に落とすようにしました。

モデルがツールを呼んだ後の dispatcher 側はこうなります。

// dispatcher.ts
import type { ToolUseBlock } from "@anthropic-ai/sdk/resources/messages.mjs";
import { reconcile } from "./reconciler.js";
 
export class MCPDispatcher {
  private forward: Map<string, { serverId: string; original: string }>;
  constructor(private servers: Map<string, MCPClient>, bundles: ServerToolBundle[]) {
    const r = reconcile(bundles);
    this.forward = r.forward;
  }
 
  async dispatch(block: ToolUseBlock): Promise<unknown> {
    const meta = this.forward.get(block.name);
    if (!meta) {
      throw new Error(`unknown tool: ${block.name}`);
    }
    const server = this.servers.get(meta.serverId);
    if (!server) {
      throw new Error(`server ${meta.serverId} not registered`);
    }
    return server.callTool(meta.original, block.input as Record<string, unknown>);
  }
}

このディスパッチャは、モデルが返した tool_use ブロックを受けて、元のサーバの元のツール名に解決し直してから MCP クライアントを叩きます。MCPClient の callTool シグネチャは利用している MCP 実装に合わせて読み替えてください。

dispatcher のエラー処理にも一言。unknown tool が出たときに即座に例外を投げると、エージェントのループ全体が落ちます。私は最初の実装でそうしてしまい、Cowork のスケジュールタスク 1 本ぶんが空振りした記憶があります。今は「未知のツール名はモデルに tool_result でエラー文字列を返す」設計に変えていて、モデルが次の turn でリカバリを試みる余地を残しています。エラー文字列には「このツール名は存在しません。利用可能なツールは: github__create_issue, linear__create_issue, ...」のように選択肢を列挙すると、Sonnet 4.6 は次の turn でほぼ正解に戻ってきます。

description を「出所タグ」で正規化する

name のリネームだけで衝突は解けますが、私の観測では「description が同じ」 2 つのツールが残ると、モデルがプレフィックスを無視して片方を選び続ける現象が出ました。とくに github__create_issue と linear__create_issue のように、両方の description に「Create a new issue」とだけ書かれている場合、モデルは name の prefix を意味のあるシグナルとして十分に重視してくれません。

そこで Reconciler に description の正規化を足しました。

function tagDescription(serverId: string, tool: Tool): Tool {
  const labelMap: Record<string, string> = {
    github: "[GitHub]",
    linear: "[Linear]",
    jira: "[Jira]",
    slack: "[Slack]",
    notion: "[Notion]",
  };
  const tag = labelMap[serverId] ?? `[${serverId}]`;
  const original = tool.description ?? "";
  if (original.startsWith(tag)) return tool;
  return { ...tool, description: `${tag} ${original}`.trim() };
}

シンプルですが効きます。description の冒頭にタグを付けただけで、私の手元では誤呼び出し率が 38% から 6% まで下がりました。タグは角括弧で囲んで視覚的に切り分けるのがコツで、モデルはタグの中身を「補助的なラベル」として認識します。description が長いツールでは、タグの後ろに改行を入れて元の文章を保ったほうが読みやすいです。

MCP サーバを動的に追加・削除するための再構築

開発中の Claude Agent SDK アプリでは、ユーザーが「Slack を接続した」「Discord を切断した」のような操作で MCP サーバが増減します。サーバが増減するたびに tools 配列を再構築しなければなりませんが、Anthropic の prompt cache を併用していると、ツール一覧が変わった瞬間にキャッシュが破棄されて月額コストが跳ねます。私は AdMob 関連の MCP を 4 つ束ねている案件で、これに気づかず月額 12% ぶんのキャッシュ恩恵を失ったことがあります。

対策として、サーバの増減を吸収する MCPManager を一段挟みます。

// mcp-manager.ts
type Listener = (state: ReconciledTools) => void;
 
export class MCPManager {
  private bundles = new Map<string, ServerToolBundle>();
  private listeners: Listener[] = [];
  private current!: ReconciledTools;
 
  register(b: ServerToolBundle) {
    this.bundles.set(b.serverId, b);
    this.rebuild();
  }
  unregister(serverId: string) {
    this.bundles.delete(serverId);
    this.rebuild();
  }
  onChange(l: Listener) { this.listeners.push(l); }
 
  private rebuild() {
    this.current = reconcile([...this.bundles.values()]);
    for (const l of this.listeners) l(this.current);
  }
  snapshot() { return this.current; }
}

MCPManager の onChange を購読しておけば、ツール一覧が変わるたびにキャッシュ・ブレークポイントの再設計や、進行中のエージェントセッションを「次の turn から新しいツール一覧で動かす」と切り替えられます。注意点は、進行中のセッションのまっただ中でツール一覧を入れ替えないことです。モデルが前の turn で覚えた github__create_issue を呼ぼうとして、次の turn でその name が消えているとリクエストが 400 を返します。turn の境界でだけ入れ替える設計にしました。

本番で踏んだ失敗パターンを 3 つ整理する

ここまでの実装を運用したうえで、私が本番で踏んだ失敗を 3 つ共有します。読者のプロジェクトでも同じ罠が待っていると思います。

第 1 の落とし穴は stale alias です。ある日 GitHub MCP がアップデートされてツール名が create_issue から issues_create に変わったとき、Reconciler は新しい名前を吸い込んだのですが、prompt cache に古いシステムプロンプトと古い tools 配列が残っていました。モデルは古い github__create_issue を呼ぼうとし、API は 400 を返し、エージェントが暴走的にリトライしてレートリミットに当たりました。対処は、Reconciler の出力ハッシュをキャッシュキーの一部に含め、ハッシュが変わったら明示的に新しい breakpoint を切ることです。

第 2 は description drift です。同じ name の 2 つのツールの description が、両方のサーバ側で別々に更新されていくと、片方だけ表現が変わっていって、ある日突然モデルが別の方を選び始める、という挙動が起きます。description の正規化で出所タグを付けた後も、本文の差異までは整わないからです。私は週次で forward マップの description をダンプして、人間が目視で違和感を拾うレビューを Cowork のスケジュールタスクに組み込みました。AdMob 月次レポートと同じ枠で動かしています。

第 3 は schema 衝突 です。同名のツールでも、input_schema が違うことがあります（例: GitHub の create_issue は repo を必須、Linear は team_id を必須）。Reconciler が name しか見ずにマージすると、モデルが片方のスキーマで呼んだときにもう一方のサーバが弾く事故が起きます。プレフィックス付けで物理的に別の name にすれば回避できますが、衝突がない場合でも「同名なのに schema が違う」状態が将来生まれることを想定して、schema の SHA-256 をキーに「同じ name で違う schema があれば強制的にプレフィックスを付ける」セーフティを Reconciler に足しました。

function schemaHash(t: Tool): string {
  // 構造の差をハッシュ化（実装は crypto.subtle.digest 等）
  return JSON.stringify(t.input_schema, Object.keys(t.input_schema).sort());
}

3 つの失敗パターンに加えて、運用 3 ヶ月で気づいた小さな罠を 2 つ書き残しておきます。

1 つ目は、ツール description の長さがモデルの選択精度にじわじわ効く点です。[GitHub] Create a new issue のような短いタグ付き description だと、Sonnet 4.6 はサーバ名の前置を信号として弱く扱います。[GitHub] Create a new issue in a repository. Use this for code-related bug reports, feature requests, and pull-request discussions on the GitHub side. のように、機能の境界を 1〜2 文で書き足すと、私の手元では誤呼び出し率がさらに 3% 下がりました。description は短くまとめたくなりますが、衝突する name を持つときに限ってはむしろ厚めにしたほうが効きます。

2 つ目は、エージェントの「最初の turn」だけ誤呼び出し率が突出する現象です。会話履歴がまだ薄い段階では、モデルがプレフィックスを切り捨てて元のツール名で呼ぼうとすることがあります。対策として、私はシステムプロンプトに「ツール名は full name で正確に呼んでください。例: github__create_issue と linear__create_issue は別物です」と一文だけ足しました。これを書くと、初回 turn の誤呼び出し率も他の turn と同じレベルまで落ち着きます。

セーフティが働いていなかった — schemaHash を実測で作り直す

上の schemaHash は「同じ name で違う schema があれば強制的にプレフィックスを付ける」ためのセーフティとして置いたものでした。読み返していて、手が止まりました。JSON.stringify の第 2 引数はソート用の比較関数ではなく、replacer です。配列を渡すと「そのキーだけを残す」フィルタとして働きます。

サンドボックス（Linux・Node v22.22.3）で記事のコードをそのまま走らせた出力がこれです。

GitHub : {"properties":{},"required":["repo","title"],"type":"object"}
Linear : {"properties":{},"required":["team_id","title"],"type":"object"}

properties が空のオブジェクトになっています。replacer の配列はネストの全階層に適用されるため、トップレベルのキー一覧（type / properties / required）に含まれない repo や title は、子の階層でまるごと落ちます。一方で配列の要素は replacer の対象外なので、required だけが素通りして残ります。スキーマの本体が消えたまま、それらしいハッシュが返ってくるという、いちばん気づきにくい壊れ方でした。

どれくらい見逃すのかを測りました。ベースのスキーマ（repo / title / labels を持つ create_issue）に対して、上流の更新で実際に起こりうる差分を 5 種類当てて、記事の実装と修正版でそれぞれ「別スキーマだと検出できるか」を比べています。

5 件中 5 件、記事の実装は「同じスキーマ」と答えました。required が変わらない限り差分が見えないので、当然といえば当然です。そして上流の MCP サーバがバージョンを上げるとき、必須項目まで一緒に変える改修はむしろ少数派です。つまりこのセーフティは、いちばん起きやすい種類のドリフトに対してだけ、沈黙していたことになります。

正しい実装は、キー順を再帰的に正規化してから 1 本のダイジェストにします。

// schema-hash.ts
import { createHash } from "node:crypto";
 
function canonicalize(v: unknown): unknown {
  if (Array.isArray(v)) return v.map(canonicalize);
  if (v && typeof v === "object") {
    const out: Record<string, unknown> = {};
    for (const k of Object.keys(v as object).sort()) {
      out[k] = canonicalize((v as Record<string, unknown>)[k]);
    }
    return out;
  }
  return v;
}
 
export function schemaHash(t: Tool): string {
  const canonical = JSON.stringify(canonicalize(t.input_schema));
  return createHash("sha256").update(canonical).digest("hex").slice(0, 16);
}

同じ 5 件を修正版で流すと、すべて別ハッシュになります。記事の冒頭で扱った GitHub と Linear の create_issue も、d70c028aa9e9e8da と 49816f1ac82369fd という別の値に落ちました。キー順だけが違う同一スキーマは、canonicalize を通しているため同じハッシュにまとまります。ここはセーフティの誤発火を防ぐために必要な性質で、記事の実装が偶然満たしていた数少ない点でもあります。

運用側でひとつ足しておくと効きます。Reconciler の初期化時に、name ごとの schemaHash を一覧でログへ吐いておくことです。上流が黙ってスキーマを変えた日に、差分がログの diff として残ります。私はこれを入れるまで、モデルの誤呼び出しが増えた原因をプロンプト側に探しに行って、半日ほど無駄にしていました。

自分の書いたコードを自分で疑う機会は、意外と訪れません。個人開発ではレビューしてくれる他人がいないぶん、なおさらです。記事に載せた時点で「動いている」と信じてしまいます。ハッシュは値が返ってくるので、壊れていても気づきにくい部類でした。

テストを書くなら、比較関数そのものではなく「差分を1箇所だけ変えた入力を通して値が変わるか」を書くのが早いです。私はこの5パターンをそのままユニットテストに移しました。

サーバ ID は「案件ベース」ではなく「機能ベース」で切る

命名規約を共有していない他人の作ったサーバが、自分のサーバとぶつかる前提で設計しておく。MCP を扱ううえで、これは礼儀に近いものだと感じています。誰かが公開してくれたサーバを自分のエージェントに招き入れ、ツール名の意味を読み解きながら使う以上、衝突は相手の落ち度ではありません。

実運用では、サーバ ID を「機能ベース」で切るほうが、長く保ちます。私は最初、案件ごとにサーバ ID を切っていました。しかし複数の案件が同じ AdMob レポートを読み、同じ Slack に通知し、同じ GitHub にコミットする現実を見て、admob / slack / github のような「機能ベース」に揃え直しました。同じ AdMob アカウントを見る MCP を何度も登録しても、サーバ ID 自体は 1 つで済みます。

Reconciler を入れたあとも、私は週 1 回、forward マップと schemaHash の一覧をまとめて目視確認しています。新しい MCP サーバを接続したときに「あ、upload が衝突したな」と気づける状態にしておくのは、エージェントが妙な動きをしたあとに原因を探すより、はるかに楽です。

サーバを増やすことが目的にならないように、自分のエージェントに「いま本当に使うツールはどれか」を定期的に問い直す時間を取っています。AdMob レポートを書くのに GitHub MCP は不要ですし、PR レビューを書くのに Slack MCP は要りません。タスクごとに「束ねる MCP サーバの組」を切り替える設計にすれば、Reconciler の出力ハッシュも安定し、prompt cache のブレークポイントを無駄に割らずに済みます。ツール一覧が長くなるほどキャッシュの効きが「ツール一覧の差分」に左右されるので、束ねる組を小さく保つこと自体が、コストにも応答速度にも効きます。

次の一歩

今日ひとつだけ手を動かすなら、束ねている MCP サーバから list_tools を呼び、name でグルーピングして衝突を数えてみてください。たぶん、思っていたより多く見つかります。プレフィックス付けも description の正規化も、その一覧を見てからで間に合います。

すでに schemaHash のようなスキーマ比較を仕込んでいる方は、そのハッシュ関数に同じスキーマの一部だけを変えた入力を通して、値が変わるかを一度確かめてみてください。私はそれを 3 ヶ月やらないまま運用していました。

MCP は今、Anthropic 周辺だけでなく他のベンダーも実装を出し始めている段階で、命名のばらつきはむしろこれから増えていきます。Reconciler を一枚挟んでおくと、サーバが増えるたびに本体コードを直さなくて済むので、エージェントの寿命が伸びます。同じ課題に取り組んでいる方の参考になれば幸いです。

実装で詰まった部分は、stand.fm の音声配信 でも時々触れています。よければ覗いてみてください。