Code Mode で MCP ツールを使う

既存の Model Context Protocol（MCP）クライアント接続のツールを、Code Mode サンドボックス内に公開するには McpConnector を使います。コネクタは耐久性のあるランタイムで動作し、検出、承認、実行履歴に対応します。

このページでは、Agent が MCP サーバーを利用する場合を扱います。Code Mode を MCP サーバーとして公開する方法は、Code Mode MCP サーバーのパターンを参照してください。

前提条件

次が必要です。

耐久性のある Code Mode ランタイムを設定したプロジェクト。このセットアップで Worker Loader バインディングと CodemodeRuntime のエクスポートが揃います。
既存の Agents SDK MCP 接続。接続の作成と認可は McpClient API を参照してください。

Code Mode をインストールする

プロジェクトにまだ Code Mode がない場合は、@cloudflare/codemode をインストールします。
npm i @cloudflare/codemode
yarn add @cloudflare/codemode
pnpm add @cloudflare/codemode
bun add @cloudflare/codemode

MCP コネクタを作成する

コネクタは専用ファイルに作成します。特別なファイル名や import 構文は不要で、通常のクラスです。

src/github-connector.jsjs

import { McpConnector } from "@cloudflare/codemode";

export class GithubConnector extends McpConnector {
	connection;

	constructor(ctx, env, connection) {
		super(ctx, env);
		this.connection = connection;
	}

	name() {
		return "github";
	}

	instructions() {
		return "Use for GitHub repositories, issues, and pull requests.";
	}

	createConnection() {
		return this.connection;
	}

	tool(name, tool) {
		if (name === "create_issue") {
			return { ...tool, requiresApproval: true };
		}

		return tool;
	}
}

src/github-connector.tsts

import {
	McpConnector,
	type ConnectorTool,
	type McpConnectionLike,
} from "@cloudflare/codemode";

export class GithubConnector extends McpConnector<Env> {
	private connection: McpConnectionLike;

	constructor(
		ctx: DurableObjectState | ExecutionContext,
		env: Env,
		connection: McpConnectionLike,
	) {
		super(ctx, env);
		this.connection = connection;
	}

	override name() {
		return "github";
	}

	protected override instructions() {
		return "Use for GitHub repositories, issues, and pull requests.";
	}

	protected override createConnection() {
		return this.connection;
	}

	protected override tool(
		name: string,
		tool: ConnectorTool,
	): ConnectorTool {
		if (name === "create_issue") {
			return { ...tool, requiresApproval: true };
		}

		return tool;
	}
}

createConnection() は既存の Agents SDK 接続を返します。name() はサンドボックスのグローバル名を定義するため、このコネクタのメソッドは github 配下に公開されます。ランタイムごとにコネクタ名は一意にしてください。

McpConnector は、検出した MCP ツールごとに型付きのサンドボックスメソッドを 1 つ作成します。メソッドの型は MCP スキーマから導出します。各メソッドは connection.client.callTool() 経由で元のツールを呼び出します。

コネクタは MCP ツール名を有効な JavaScript 識別子に正規化します。たとえば list-pull.requests は list_pull_requests、3d-render は _3d_render、delete は delete_ になります。2 つの元の名前が同じ識別子になると、コネクタはエラーを投げます。その場合は toolName() をオーバーライドして区別してください。

tool() デコレーションフックは、正規化後の名前で各生成メソッドを受け取ります。この例では、フックが create_issue に承認を要求します。耐久性のあるランタイムはそのメソッドの実行前に一時停止し、承認後に実行を再開します。

コネクタをランタイムに追加する

Agent 内で既存の MCP 接続を探し、コネクタに渡します。そのうえで、Code Mode ランタイムの作成時にコネクタを含めます。

src/server.jsjs

import { Agent } from "agents";
import {
	createCodemodeRuntime,
	DynamicWorkerExecutor,
} from "@cloudflare/codemode";
import { GithubConnector } from "./github-connector";

export class Chat extends Agent {
	async codemodeRuntime() {
		await this.mcp.waitForConnections();

		const server = this.mcp
			.listServers()
			.find((server) => server.name === "github");

		if (!server) {
			throw new Error("GitHub MCP server is not registered.");
		}

		const connection = this.mcp.mcpConnections[server.id];
		if (!connection) {
			throw new Error("GitHub MCP connection is not available.");
		}

		return createCodemodeRuntime({
			ctx: this.ctx,
			executor: new DynamicWorkerExecutor({ loader: this.env.LOADER }),
			connectors: [new GithubConnector(this.ctx, this.env, connection)],
		});
	}
}

src/server.tsts

import { Agent } from "agents";
import {
	createCodemodeRuntime,
	DynamicWorkerExecutor,
} from "@cloudflare/codemode";
import { GithubConnector } from "./github-connector";

export class Chat extends Agent<Env> {
	private async codemodeRuntime() {
		await this.mcp.waitForConnections();

		const server = this.mcp
			.listServers()
			.find((server) => server.name === "github");

		if (!server) {
			throw new Error("GitHub MCP server is not registered.");
		}

		const connection = this.mcp.mcpConnections[server.id];
		if (!connection) {
			throw new Error("GitHub MCP connection is not available.");
		}

		return createCodemodeRuntime({
			ctx: this.ctx,
			executor: new DynamicWorkerExecutor({ loader: this.env.LOADER }),
			connectors: [
				new GithubConnector(this.ctx, this.env, connection),
			],
		});
	}
}

codemodeRuntime() を await し、runtime.tool() をモデルへ codemode ツールとして渡します。承認、拒否、ロールバック、スニペットの各メソッドを呼ぶ前にも、ヘルパーを再度 await してください。ハイバネーション後に MCP 接続の復元が完了していることを保証します。

ランタイムが Think エージェントに属する場合は、MCP ツールをモデルの直接ツールセットから外します。

import { Think } from "@cloudflare/think";

export class Chat extends Think {
	includeMcpTools = false;
	waitForMcpConnections = true;
}

import { Think } from "@cloudflare/think";

export class Chat extends Think<Env> {
    includeMcpTools = false;
    waitForMcpConnections = true;
}

includeMcpTools = false は、Think の自動 getAITools() 呼び出しをスキップします。MCP 接続は McpConnector から引き続き利用できます。

モデルにツールの検出と呼び出しを任せる

未知のメソッドを呼ぶ前に、codemode.search() と codemode.describe() を使うようモデルに指示します。モデルが生成したサンドボックスコードは、生成済みメソッドを検出して呼び出せます。
```
async () => {
	const matches = await codemode.search("open pull requests");
	const docs = await codemode.describe(matches.results[0].path);

	const pullRequests = await github.list_pull_requests({
		owner: "cloudflare",
		repo: "agents",
		state: "open",
	});

	return { docs, pullRequests };
};
```
codemode.search() はランク付けされたコネクタメソッドを返します。codemode.describe() はコネクタまたはメソッドの TypeScript ドキュメントを返します。モデルは必要なときだけツールの詳細を読み込めます。

モデルが github.create_issue() を呼ぶと、ランタイムは一時停止した実行を返します。ランタイム経由でその実行を承認すると、MCP ツールが実行され、同じサンドボックスプログラムが続行します。

AI SDK のツールコレクションを使う

耐久性のある承認や codemode.search() / codemode.describe() を使わない、より小さな統合では、Agents SDK のツールコレクションを createCodeTool() に直接渡します。

import { DynamicWorkerExecutor } from "@cloudflare/codemode";
import { createCodeTool } from "@cloudflare/codemode/ai";

await this.mcp.waitForConnections();

const executor = new DynamicWorkerExecutor({ loader: this.env.LOADER });
const codemode = createCodeTool({
	tools: this.mcp.getAITools(),
	executor,
});

import { DynamicWorkerExecutor } from "@cloudflare/codemode";
import { createCodeTool } from "@cloudflare/codemode/ai";

await this.mcp.waitForConnections();

const executor = new DynamicWorkerExecutor({ loader: this.env.LOADER });
const codemode = createCodeTool({
	tools: this.mcp.getAITools(),
	executor,
});

この方法では、MCP ツールはデフォルトの codemode 名前空間に公開されます。コネクタランタイムの耐久性のある一時停止、承認、再開の流れは使いません。ツールが副作用を起こしうる場合や、モデルがオンデマンドで検出する必要がある場合は McpConnector を使ってください。

getAITools() は、MCP の入出力スキーマを AI SDK 向けに変換します。Agents SDK はその変換済みスキーマを再利用し、各ライブ接続は同じ最新カタログを保持します。生の MCP カタログを確認するだけなら、代わりに this.mcp.listTools() を使います。