MCP の概要
Model Context Protocol（MCP） は、AIモデルが外部のツールやリソースを発見し、やり取りできるように設計されたオープン標準です。AIエージェント向けのユニバーサルなプラグインシステムのようなもので、ツールがどの言語で実装されているかや、どこでホストされているかに関係なく利用できるようにします。
Mastra は MCP を用いて、エージェントを外部のツールサーバーに接続します。
MCP クライアントでサードパーティ製ツールを使う
Mastra は、複数の MCP サーバーへの接続を管理し、それらのツールへアクセスするための MCPClient クラスを提供します。
インストール
まだインストールしていない場合は、Mastra MCP パッケージを導入します:
npm install @mastra/mcp@latestMCPServer の登録
Mastra に MCP サーバーを登録して、ログ出力を有効化し、設定済みのツールや各種統合機能にアクセスできるようにします:
import { Mastra } from "@mastra/core";
import { myMcpServer } from "./mcpServers";
export const mastra = new Mastra({
mcpServers: { myMcpServer },
});MCPClient の設定
接続したいサーバーのマップを渡して MCPClient を構成します。サブプロセス（Stdio）経由、または HTTP（SSE フォールバック付きの Streamable HTTP）経由の接続に対応しています。
import { MCPClient } from "@mastra/mcp";
const mcp = new MCPClient({
servers: {
// Stdio example
sequential: {
command: "npx",
args: ["-y", "@modelcontextprotocol/server-sequential-thinking"],
},
// HTTP example
weather: {
url: new URL("http://localhost:8080/mcp"),
requestInit: {
headers: {
Authorization: "Bearer your-token",
},
},
},
},
});詳細な設定オプションは、MCPClient のリファレンスドキュメントを参照してください。
静的設定と動的設定
MCPClient には、接続中のサーバーからツールを取得するための 2 つのアプローチがあり、さまざまなアプリケーションアーキテクチャに適しています:
| 機能 | 静的設定（await mcp.getTools()） | 動的設定（await mcp.getToolsets()） |
|---|---|---|
| ユースケース | 単一ユーザー、静的設定（例: CLI ツール） | 複数ユーザー、動的設定（例: SaaS アプリ） |
| 設定方法 | エージェント初期化時に固定 | リクエストごとに動的 |
| 認証情報 | すべての利用で共有 | ユーザー/リクエストごとに変更可能 |
| エージェント設定 | Agent コンストラクタでツールを追加 | generate() または stream() のオプションでツールを渡す |
-
静的設定（
getTools()）: すべての設定済みサーバーからすべてのツールを取得します。ツール構成（API キーなど）が固定で、全ユーザーや全リクエスト間で共有される場合に最適です。通常はこれを一度だけ呼び出し、Agentを定義する際にtoolsプロパティへ結果を渡します。 参考:getTools()import { Agent } from "@mastra/core/agent"; // ... mcp client setup const agent = new Agent({ // ... other agent config tools: await mcp.getTools(), }); -
動的設定（
getToolsets()）: 設定がリクエスト単位やユーザー単位で変わりうるシナリオ向け（例: マルチテナント環境でテナントごとに異なる API キー）。getToolsets()の結果を、エージェントのgenerate()またはstream()メソッドのtoolsetsオプションに渡します。 参考:getToolsets()import { Agent } from "@mastra/core/agent"; // ... agent setup without tools initially async function handleRequest(userPrompt: string, userApiKey: string) { const userMcp = new MCPClient({ /* config with userApiKey */ }); const toolsets = await userMcp.getToolsets(); const response = await agent.stream(userPrompt, { toolsets, // 動的なツールセットを渡す }); // ... handle response await userMcp.disconnect(); }
MCP レジストリに接続する
MCP サーバーはレジストリ経由で発見できます。MCPClient を使って主要なレジストリに接続する方法は以下のとおりです:
Klavis AI
Klavis AI は、ホスティング型でエンタープライズ認証に対応した高品質な MCP サーバーを提供します。
import { MCPClient } from "@mastra/mcp";
const mcp = new MCPClient({
servers: {
salesforce: {
url: new URL("https://salesforce-mcp-server.klavis.ai/mcp/?instance_id={private-instance-id}"),
},
hubspot: {
url: new URL("https://hubspot-mcp-server.klavis.ai/mcp/?instance_id={private-instance-id}"),
},
},
});Klavis AI は、本番環境向けにエンタープライズグレードの認証とセキュリティを提供します。
Mastra と Klavis の統合方法の詳細は、ドキュメント をご覧ください。
MCP サーバーでツールを共有する
独自の Mastra ツールを作成した場合、Mastra の MCPServer クラスを使って、任意の MCP 互換クライアントに公開できます。
同様に、Mastra の Agent と Workflow のインスタンスも MCPServer 経由でツールとして公開できます。これにより、他の MCP クライアントがエージェントに「質問」して対話したり、ワークフローを実行したりできます。MCPServer の設定で提供された各エージェントは、その description プロパティを用いて ask_<agentKey> という名前のツールに変換されます。各ワークフローは、その inputSchema と description を用いて run_<workflowKey> という名前のツールに変換されます。
これにより、他者はあなたのコードベースに直接アクセスすることなく、ツール、エージェント、ワークフローを利用できます。
MCPServer の使用
共有したい名前、バージョン、Mastra のツール、エージェント、ワークフローを指定して MCPServer を初期化します。
import { MCPServer } from "@mastra/mcp";
import { Agent } from "@mastra/core/agent";
import { openai } from "@ai-sdk/openai";
import { weatherTool } from "./tools"; // あなたの Mastra ツール
import { weatherAgent } from "./agents"; // あなたの Mastra Agent
import { dataWorkflow } from "./workflows"; // あなたの Mastra Workflow
const server = new MCPServer({
name: "My Custom Server",
version: "1.0.0",
tools: { weatherTool }, // ここにツールを指定
agents: { weatherAgent }, // ここにエージェントを指定
workflows: { dataWorkflow }, // ここにワークフローを指定
});
// サーバーを起動（例: CLI ツール向けに stdio を使用）
// await server.startStdio();
// あるいは startSSE() を使用して HTTP サーバーと統合
// 詳細は MCPServer リファレンスを参照エージェントをツールとして公開するには、空でない description 文字列が必要です。同様に、ワークフローを公開する場合も、その description は空でない文字列である必要があります。いずれかの description が欠落しているか空の場合、初期化時に MCPServer はエラーをスローします。
ワークフローはツールの入力にその inputSchema を使用します。
構造化出力を持つツール
ツールの出力に特定の構造を持たせるために、outputSchema を定義できます。これは、ツールが一貫性のある予測可能な形式でデータを返し、クライアント側で検証できるようにするのに有用です。
ツールに outputSchema が含まれている場合、その execute 関数は必ずオブジェクトを返さなければなりません。返されるオブジェクトは outputSchema に適合している必要があります。Mastra はサーバー側とクライアント側の両方でこの出力を自動的に検証します。
以下は outputSchema を持つツールの例です:
import { createMCPTool } from '@mastra/mcp';
import { z } from 'zod';
export const structuredTool = createMCPTool({
id: 'structuredTool',
description: 'A test tool that returns structured data.',
inputSchema: z.object({
input: z.string().describe('Some input string.'),
}),
outputSchema: z.object({
processedInput: z.string().describe('The processed input string.'),
timestamp: z.string().describe('An ISO timestamp.'),
}),
execute: async (params, { elicitation, extra }) => {
// When outputSchema is defined, you must return an object
return {
processedInput: `processed: ${params.input}`,
timestamp: new Date().toISOString(),
};
},
});このツールが呼び出されると、MCP クライアントは構造化データとそのテキスト表現の両方を受け取ります。
Tool result
{
"content": [
{
"type": "text",
"text": "{\"processedInput\": \"hello\", \"timestamp\": \"2025-06-19T16:53:16.472Z\"}"
}
],
"structuredContent": {
"processedInput": "processed: hello",
"timestamp": "2025-06-19T16:53:16.472Z",
}
}詳細な使い方と例については、MCPServer リファレンスドキュメントを参照してください。