Mastraでのモデルコンテキストプロトコル（MCP）の使用
モデルコンテキストプロトコル（MCP） は、AIモデルが外部ツールやリソースを発見し、相互作用するための標準化された方法です。
概要
MastraのMCPは、ツールサーバーに接続するための標準化された方法を提供します。StdioとHTTP（Streamable HTTPをサポートし、SSEにフォールバック）をサポートしています。
インストール
pnpmを使用する場合：
pnpm add @mastra/mcp@latestnpmを使用する場合：
npm install @mastra/mcp@latestコード内でMCPを使用する
MCPClientクラスは、複数のMCPクライアントを管理することなく、Mastraアプリケーションで複数のツールサーバーを管理する方法を提供します。MCPConfiguration内部で使用されるMastraMCPClientは、サーバー設定に基づいてトランスポートタイプを自動的に検出するようになりました：
commandを提供する場合、Stdioトランスポートを使用します。urlを提供する場合、最初にStreamable HTTPトランスポートを試み、初期接続が失敗した場合はレガシーSSEトランスポートにフォールバックします。
以下は設定例です：
import { MCPClient } from "@mastra/mcp";
import { Agent } from "@mastra/core/agent";
import { openai } from "@ai-sdk/openai";
const mcp = new MCPClient({
servers: {
// Stdio例
sequential: {
command: "npx",
args: ["-y", "@modelcontextprotocol/server-sequential-thinking"],
},
// HTTP例（最初にStreamable HTTPを試み、その後SSEにフォールバック）
weather: {
url: new URL("http://localhost:8080/mcp"), // Streamable HTTPのベースURLを使用
requestInit: {
headers: {
Authorization: "Bearer your-token",
},
},
},
},
});ツールとツールセット
MCPClientクラスはMCPツールにアクセスするための2つの方法を提供しており、それぞれ異なるユースケースに適しています：
ツールの使用（getTools()）
以下の場合にこのアプローチを使用します：
- 単一のMCP接続がある場合
- ツールが単一のユーザー/コンテキストによって使用される場合
- ツール設定（APIキー、認証情報）が一定の場合
- 固定されたツールセットでAgentを初期化したい場合
const agent = new Agent({
name: "CLI Assistant",
instructions: "You help users with CLI tasks",
model: openai("gpt-4o-mini"),
tools: await mcp.getTools(), // ツールはエージェント作成時に固定される
});ツールセットの使用（getToolsets()）
以下の場合にこのアプローチを使用します：
- リクエストごとのツール設定が必要な場合
- ツールがユーザーごとに異なる認証情報を必要とする場合
- マルチユーザー環境（Webアプリ、APIなど）で実行する場合
- ツール設定を動的に変更する必要がある場合
const mcp = new MCPClient({
servers: {
example: {
command: "npx",
args: ["-y", "@example/fakemcp"],
env: {
API_KEY: "your-api-key",
},
},
},
});
// このユーザー用に設定された現在のツールセットを取得
const toolsets = await mcp.getToolsets();
// ユーザー固有のツール設定でエージェントを使用
const response = await agent.stream(
"Mastraの新機能は何ですか？また、天気はどうですか？",
{
toolsets,
},
);MCP レジストリ
MCPサーバーは、キュレーションされたツールコレクションを提供するレジストリを通じてアクセスできます。 私たちは、最適なMCPサーバーの調達先を見つけるのに役立つMCP レジストリ レジストリ をキュレーションしていますが、以下では私たちのお気に入りのいくつかからツールを使用する方法を説明します：
mcp.run レジストリ
mcp.run を使用すると、事前認証された安全なMCPサーバーを簡単に呼び出すことができます。mcp.runのツールは無料で、完全に管理されているため、エージェントはSSE URLだけを必要とし、ユーザーがインストールしたどのツールでも使用できます。MCPサーバーはプロファイル にグループ化され、固有のSSE URLでアクセスされます。
各プロファイルについて、署名付きの固有のURLをコピー/ペーストして、次のようにMCPClientに入力できます：
const mcp = new MCPClient({
servers: {
marketing: {
url: new URL(process.env.MCP_RUN_SSE_URL!),
},
},
});重要：mcp.run の各SSE URLには、パスワードのように扱うべき固有の署名が含まれています。SSE URLを環境変数として読み込み、アプリケーションコードの外部で管理するのがベストです。
MCP_RUN_SSE_URL=https://www.mcp.run/api/mcp/sse?nonce=...Composio.dev レジストリ
Composio.dev は、Mastraと簡単に統合できるSSEベースのMCPサーバー のレジストリを提供しています。Cursor用に生成されるSSE URLはMastraと互換性があり、設定で直接使用できます：
const mcp = new MCPClient({
servers: {
googleSheets: {
url: new URL("https://mcp.composio.dev/googlesheets/[private-url-path]"),
},
gmail: {
url: new URL("https://mcp.composio.dev/gmail/[private-url-path]"),
},
},
});Composio提供のツールを使用する場合、エージェントとの会話を通じて直接サービス（Google SheetsやGmailなど）で認証できます。ツールには認証機能が含まれており、チャット中にプロセスをガイドします。
注意：Composio.devの統合は、SSE URLがあなたのアカウントに紐づけられており、複数のユーザーには使用できないため、個人的な自動化などの単一ユーザーシナリオに最適です。各URLは単一アカウントの認証コンテキストを表します。
Smithery.ai レジストリ
Smithery.ai はMastraで簡単に使用できるMCPサーバーのレジストリを提供しています：
// Unix/Mac
const mcp = new MCPClient({
servers: {
sequentialThinking: {
command: "npx",
args: [
"-y",
"@smithery/cli@latest",
"run",
"@smithery-ai/server-sequential-thinking",
"--config",
"{}",
],
},
},
});
// Windows
const mcp = new MCPClient({
servers: {
sequentialThinking: {
command: "cmd",
args: [
"/c",
"npx",
"-y",
"@smithery/cli@latest",
"run",
"@smithery-ai/server-sequential-thinking",
"--config",
"{}",
],
},
},
});この例は、Smitheryドキュメントのクロード統合例から適応されています。
MCPサーバーでツールを除外する
MCPサーバーからのツールは、await mcp.getTools()またはawait mcp.getToolsets()を呼び出すと、プレーンなJavaScriptオブジェクトとして返されます。これにより、エージェントに渡す前にツールを簡単にフィルタリングしたり除外したりすることができます。
ツール除外の例
MCPサーバーが3つのツール（weather、stockPrice、news）を公開しているが、エージェントからnewsツールを除外したい場合を考えてみましょう。ツールオブジェクトをフィルタリングすることでこれを実現できます：
import { MCPClient } from "@mastra/mcp";
import { Agent } from "@mastra/core/agent";
import { openai } from "@ai-sdk/openai";
const mcp = new MCPClient({
servers: {
myServer: {
command: "npx",
args: ["tsx", "my-mcp-server.ts"],
},
},
});
// MCPサーバーからすべてのツールを取得
const allTools = await mcp.getTools();
// 'news'ツールを除外（ツール名は'serverName_toolName'の形式で名前空間が設定されています）
const filteredTools = Object.fromEntries(
Object.entries(allTools).filter(([toolName]) => toolName !== "myServer_news")
);
// フィルタリングされたツールのみをエージェントに渡す
const agent = new Agent({
name: "Selective Agent",
instructions: "You can access only selected tools.",
model: openai("gpt-4"),
tools: filteredTools,
});.filter()関数内で任意のロジックを使用して、名前、タイプ、またはその他のプロパティによってツールを除外できます。このアプローチは、リクエストごとにツールセットを動的にフィルタリングしたい場合のgetToolsets()でも同様に機能します。
もう一つのアプローチは、使用したいツールを分割代入するか、使用したくないツールを除外することです。
// 分割代入したオブジェクトから不要なツールを削除
const { myServer_news, ...filteredTools } = await mcp.getTools();
// フィルタリングされたツールのみをエージェントに渡す
const agent = new Agent({
name: "Selective Agent",
instructions: "You can access only selected tools.",
model: openai("gpt-4"),
tools: filteredTools,
});// 分割代入したオブジェクトから必要なツールを選択
const { myServer_weather, myServer_stockPrice } = await mcp.getTools();
// 選択したツールのみをエージェントに渡す
const agent = new Agent({
name: "Selective Agent",
instructions: "You can access only selected tools.",
model: openai("gpt-4"),
tools: { myServer_weather, myServer_stockPrice },
});この例は、Smitheryドキュメントのクロード統合例から適応されています。
// Unix/Mac
const mcp = new MCPConfiguration({
servers: {
sequentialThinking: {
command: "npx",
args: [
"-y",
"@smithery/cli@latest",
"run",
"@smithery-ai/server-sequential-thinking",
"--config",
"{}",
],
},
},
});
// Windows
const mcp = new MCPConfiguration({
servers: {
sequentialThinking: {
command: "cmd",
args: [
"/c",
"npx",
"-y",
"@smithery/cli@latest",
"run",
"@smithery-ai/server-sequential-thinking",
"--config",
"{}",
],
},
},
});この例は、Smitheryドキュメントのクロード統合例から適応されています。