Skip to Content
ドキュメントツールとMCPMCP概要

MCP 概要

Model Context Protocol (MCP) は、AIモデルが外部ツールやリソースを発見し、相互作用できるように設計されたオープンスタンダードです。これはAIエージェント向けの汎用プラグインシステムと考えることができ、エージェントがツールの記述言語やホスティング場所に関係なくツールを使用できるようにします。

Mastraは、エージェントを外部ツールサーバーに接続するためにMCPを使用しています。

MCP クライアントでサードパーティツールを使用する

Mastraは、1つまたは複数のMCPサーバーへの接続を管理し、そのツールにアクセスするためのMCPClientクラスを提供しています。

インストール

まだインストールしていない場合は、Mastra MCPパッケージをインストールしてください：

npm install @mastra/mcp@latest

MCPServerの登録

MCPサーバーをMastraに登録して、ログ記録や設定されたツールと統合へのアクセスを有効にします：

src/mastra/index.ts
import { Mastra } from "@mastra/core";
import { myMcpServer } from "./mcpServers";
 
export const mastra = new Mastra({
  mcpServers: { myMcpServer },
});

MCPClientの設定

MCPClientは、接続したいサーバーのマップで設定します。サブプロセス（Stdio）またはHTTP（SSEフォールバック付きのストリーム可能なHTTP）を介した接続をサポートしています。

import { MCPClient } from "@mastra/mcp";
 
const mcp = new MCPClient({
  servers: {
    // Stdioの例
    sequential: {
      command: "npx",
      args: ["-y", "@modelcontextprotocol/server-sequential-thinking"],
    },
    // HTTPの例
    weather: {
      url: new URL("http://localhost:8080/mcp"),
      requestInit: {
        headers: {
          Authorization: "Bearer your-token",
        },
      },
    },
  },
});

詳細な設定オプションについては、MCPClientリファレンスドキュメントを参照してください。

静的vs動的ツール設定

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の設定
 
const agent = new Agent({
  // ... その他のエージェント設定
  tools: await mcp.getTools(),
});

  • 動的設定（getToolsets()）： リクエストごとまたはユーザーごとに設定が変更される可能性があるシナリオ（例：マルチユーザーアプリケーションで異なるテナントに対して異なるAPIキーを使用する場合）向けに設計されています。getToolsets()の結果をエージェントのgenerate()またはstream()メソッドのtoolsetsオプションに渡します。 リファレンス：getToolsets()

    import { Agent } from "@mastra/core/agent";
// ... 最初はツールなしでエージェントを設定
 
async function handleRequest(userPrompt: string, userApiKey: string) {
  const userMcp = new MCPClient({
    /* userApiKeyを含む設定 */
  });
  const toolsets = await userMcp.getToolsets();
 
  const response = await agent.stream(userPrompt, {
    toolsets, // 動的ツールセットを渡す
  });
  // ... レスポンスを処理
  await userMcp.disconnect();
}

MCPレジストリへの接続

MCPサーバーはレジストリを通じて発見できます。MCPClientを使用して人気のあるレジストリに接続する方法は以下の通りです：

mcp.run は事前認証済みの管理されたMCPサーバーを提供します。ツールはプロファイルにグループ化され、それぞれが一意の署名付きURLを持ちます。

import { MCPClient } from "@mastra/mcp";
 
const mcp = new MCPClient({
  servers: {
    marketing: { // プロファイル名の例
      url: new URL(process.env.MCP_RUN_SSE_URL!), // mcp.runプロファイルからURLを取得
    },
  },
});

重要： mcp.runのSSE URLはパスワードのように扱ってください。環境変数などに安全に保存してください。

.env
MCP_RUN_SSE_URL=https://www.mcp.run/api/mcp/sse?nonce=...

MCPサーバーでツールを共有する

独自のMastraツールを作成した場合、MastraのMCPServerクラスを使用して、MCP互換のクライアントにそれらを公開できます。

同様に、MastraのAgentとWorkflowインスタンスもMCPServerを介してツールとして公開できます。これにより、他のMCPクライアントがエージェントに「質問」したり、ワークフローを実行したりして、あなたのエージェントと対話できるようになります。MCPServerの設定で提供される各エージェントは、エージェントのdescriptionプロパティを使用して、ask_<agentKey>という名前のツールに変換されます。各ワークフローは、そのinputSchemaとdescriptionを使用して、run_<workflowKey>という名前のツールに変換されます。

これにより、他の人があなたのコードベースに直接アクセスすることなく、あなたのツール、エージェント、ワークフローを使用できるようになります。

MCPServerの使用

MCPServerは、名前、バージョン、および共有したいMastraツール、エージェント、ワークフローで初期化します。

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を使用します。

詳細な使用方法と例については、MCPServerリファレンスドキュメントを参照してください。

概要動的ツールコンテキスト