MCP サーバーへ接続する

Agent は外部の Model Context Protocol (MCP) ↗ サーバーへ接続し、そのツールを使って能力を広げられます。このチュートリアルでは、MCP サーバーへ接続し、そのツールの 1 つを使う Agent を作成します。

作るもの

次のエンドポイントを持つ Agent です。

MCP サーバーへ接続する
接続済みサーバーから利用可能なツールを一覧する
接続状態を取得する

前提条件

接続先の MCP サーバーです（このチュートリアルの公開例でも構いません）。

1. 基本の Agent を作成する

hello-world テンプレートで新しい Agent プロジェクトを作成します。
npm create cloudflare@latest -- my-mcp-client --template=cloudflare/ai/demos/hello-world
yarn create cloudflare my-mcp-client --template=cloudflare/ai/demos/hello-world
pnpm create cloudflare@latest my-mcp-client --template=cloudflare/ai/demos/hello-world

プロジェクトディレクトリへ移動します。

cd my-mcp-client

Agent の準備はできています。テンプレートは src/index.ts に最小の Agent を含みます。

import { Agent, routeAgentRequest } from "agents";

export class HelloAgent extends Agent {
	async onRequest(request) {
		return new Response("Hello, Agent!", { status: 200 });
	}
}

export default {
	async fetch(request, env) {
		return (
			(await routeAgentRequest(request, env, { cors: true })) ||
			new Response("Not found", { status: 404 })
		);
	},
};

src/index.tsts

import { Agent, routeAgentRequest } from "agents";

type Env = {
	HelloAgent: DurableObjectNamespace<HelloAgent>;
};

export class HelloAgent extends Agent<Env> {
	async onRequest(request: Request): Promise<Response> {
		return new Response("Hello, Agent!", { status: 200 });
	}
}

export default {
	async fetch(request: Request, env: Env) {
		return (
			(await routeAgentRequest(request, env, { cors: true })) ||
			new Response("Not found", { status: 404 })
		);
	},
} satisfies ExportedHandler<Env>;

2. MCP 接続エンドポイントを追加する

MCP サーバーへ接続するエンドポイントを追加します。src/index.ts の Agent クラスを更新します。

export class HelloAgent extends Agent {
	async onRequest(request) {
		const url = new URL(request.url);

		// Connect to an MCP server
		if (url.pathname.endsWith("add-mcp") && request.method === "POST") {
			const { serverUrl, name } = await request.json();

			const { id, authUrl } = await this.addMcpServer(name, serverUrl);

			if (authUrl) {
				// OAuth required - return auth URL
				return new Response(JSON.stringify({ serverId: id, authUrl }), {
					headers: { "Content-Type": "application/json" },
				});
			}

			return new Response(
				JSON.stringify({ serverId: id, status: "connected" }),
				{ headers: { "Content-Type": "application/json" } },
			);
		}

		return new Response("Not found", { status: 404 });
	}
}

src/index.tsts

export class HelloAgent extends Agent<Env> {
	async onRequest(request: Request): Promise<Response> {
		const url = new URL(request.url);

		// Connect to an MCP server
		if (url.pathname.endsWith("add-mcp") && request.method === "POST") {
			const { serverUrl, name } = (await request.json()) as {
				serverUrl: string;
				name: string;
			};

			const { id, authUrl } = await this.addMcpServer(name, serverUrl);

			if (authUrl) {
				// OAuth required - return auth URL
				return new Response(
					JSON.stringify({ serverId: id, authUrl }),
					{ headers: { "Content-Type": "application/json" } },
				);
			}

			return new Response(
				JSON.stringify({ serverId: id, status: "connected" }),
				{ headers: { "Content-Type": "application/json" } },
			);
		}

		return new Response("Not found", { status: 404 });
	}
}

addMcpServer() メソッドは MCP サーバーへ接続します。サーバーが OAuth 認証を要求する場合、認可完了のためにユーザーが開く authUrl を返します。

3. 接続をテストする

開発サーバーを起動します。
```
npm start
```

新しいターミナルで、MCP サーバーへ接続します（公開例を使います）。

curl -X POST http://localhost:8788/agents/hello-agent/default/add-mcp \
	-H "Content-Type: application/json" \
	-d '{
		"serverUrl": "https://docs.mcp.cloudflare.com/mcp",
		"name": "Example Server"
	}'

サーバー ID を含む応答が表示されます。

{
	"serverId": "example-server-id",
	"status": "connected"
}

4. 利用可能なツールを一覧する

接続済みサーバーから、どのツールが使えるかを見るエンドポイントを追加します。

export class HelloAgent extends Agent {
	async onRequest(request) {
		const url = new URL(request.url);

		// ... previous add-mcp endpoint ...

		// List MCP state (servers, tools, etc)
		if (url.pathname.endsWith("mcp-state") && request.method === "GET") {
			const mcpState = this.getMcpServers();

			return Response.json(mcpState);
		}

		return new Response("Not found", { status: 404 });
	}
}

src/index.tsts

export class HelloAgent extends Agent<Env> {
	async onRequest(request: Request): Promise<Response> {
		const url = new URL(request.url);

		// ... previous add-mcp endpoint ...

		// List MCP state (servers, tools, etc)
		if (url.pathname.endsWith("mcp-state") && request.method === "GET") {
			const mcpState = this.getMcpServers();

			return Response.json(mcpState);
		}

		return new Response("Not found", { status: 404 });
	}
}

テストします。

curl http://localhost:8788/agents/hello-agent/default/mcp-state

接続済みサーバー、接続状態、利用可能なツールがすべて表示されます。

{
	"servers": {
		"example-server-id": {
			"name": "Example Server",
			"state": "ready",
			"server_url": "https://docs.mcp.cloudflare.com/mcp",
			...
		}
	},
	"tools": [
		{
			"name": "add",
			"description": "Add two numbers",
			"serverId": "example-server-id",
			...
		}
	]
}

まとめ

次ができる Agent を作成しました。

外部の MCP サーバーへ動的に接続する
必要な場合に OAuth 認証フローを扱う
接続済みサーバーから利用可能なツールをすべて一覧する
接続状態を監視する

接続は Agent の SQL ストレージに永続化されるため、リクエストをまたいでも有効なままです。

MCP サーバーへ接続する

作るもの

前提条件

1. 基本の Agent を作成する

2. MCP 接続エンドポイントを追加する

3. 接続をテストする

4. 利用可能なツールを一覧する

まとめ

次のステップ

OAuth フローを扱う

MCP Client API