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: { // Example profile name
      url: new URL(process.env.MCP_RUN_SSE_URL!), // Get URL from mcp.run profile
    },
  },
});

重要: 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も空でない文字列である必要があります。どちらかで説明が欠けているか空の場合、MCPServerは初期化時にエラーをスローします。 ワークフローは、ツールの入力にinputSchemaを使用します。

構造化出力を持つツール

ツールの出力に特定の構造を強制するために、ツールにoutputSchemaを定義できます。これは、ツールが一貫性があり予測可能な形式でデータを返すことを保証するのに役立ち、その後クライアントによって検証できます。

ツールにoutputSchemaが含まれている場合、そのexecute関数は必ずオブジェクトを返す必要があります。オブジェクトの値はoutputSchemaに準拠している必要があります。Mastraは、サーバーとクライアントの両側でこの出力を自動的に検証します。

以下はoutputSchemaを持つツールの例です：

src/tools/structured-tool.ts
import { createTool } from '@mastra/core';
import { z } from 'zod';
 
export const structuredTool = createTool({
  description: 'A test tool that returns structured data.',
  parameters: 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 ({ input }) => {
    // outputSchemaが定義されている場合、オブジェクトを返す必要があります
    return {
      processedInput: `processed: ${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リファレンスドキュメントを参照してください。

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