Skip to main content

MCP Overview

Mastra supports the Model Context Protocol (MCP), an open standard for connecting AI agents to external tools and resources. It serves as a universal plugin system, enabling agents to call tools regardless of language or hosting environment.

Mastra can also be used to author MCP servers, exposing agents, tools, and other structured resources via the MCP interface. These can then be accessed by any system or agent that supports the protocol.

Mastra currently supports two MCP classes:

  1. MCPClient: Connects to one or many MCP servers to access their tools, resources, prompts, and handle elicitation requests.
  2. MCPServer: Exposes Mastra tools, agents, workflows, prompts, and resources to MCP compatible clients.

Getting started​

To use MCP, install the required dependency:

npm install @mastra/mcp@latest

Configuring MCPClient​

The MCPClient connects Mastra primitives to external MCP servers, which can be local packages (invoked using npx) or remote HTTP(S) endpoints. Each server must be configured with either a command or a url, depending on how it's hosted.

src/mastra/mcp/test-mcp-client.ts
import { MCPClient } from "@mastra/mcp";

export const testMcpClient = new MCPClient({
  id: "test-mcp-client",
  servers: {
    wikipedia: {
      command: "npx",
      args: ["-y", "wikipedia-mcp"],
    },
    weather: {
      url: new URL(
        `https://server.smithery.ai/@smithery-ai/national-weather-service/mcp?api_key=${process.env.SMITHERY_API_KEY}`,
      ),
    },
  },
});

See MCPClient for a full list of configuration options.

Using MCPClient with an agent​

To use tools from an MCP server in an agent, import your MCPClient and call .getTools() in the tools parameter. This loads from the defined MCP servers, making them available to the agent.

src/mastra/agents/test-agent.ts
import { openai } from "@ai-sdk/openai";
import { Agent } from "@mastra/core/agent";

import { testMcpClient } from "../mcp/test-mcp-client";

export const testAgent = new Agent({
  name: "Test Agent",
  description: "You are a helpful AI assistant",
  instructions: `
      You are a helpful assistant that has access to the following MCP Servers.
      - Wikipedia MCP Server
      - US National Weather Service

      Answer questions using the information you find using the MCP Servers.`,
  model: openai("gpt-4o-mini"),
  tools: await testMcpClient.getTools(),
});

See the Agent Class for a full list of configuration options.

Configuring MCPServer​

To expose agents, tools, and workflows from your Mastra application to external systems over HTTP(S) use the MCPServer class. This makes them accessible to any system or agent that supports the protocol.

src/mastra/mcp/test-mcp-server.ts
import { MCPServer } from "@mastra/mcp";

import { testAgent } from "../agents/test-agent";
import { testWorkflow } from "../workflows/test-workflow";
import { testTool } from "../tools/test-tool";

export const testMcpServer = new MCPServer({
  id: "test-mcp-server",
  name: "Test Server",
  version: "1.0.0",
  agents: { testAgent },
  tools: { testTool },
  workflows: { testWorkflow },
});

See MCPServer for a full list of configuration options.

Registering an MCPServer​

To make an MCP server available to other systems or agents that support the protocol, register it in the main Mastra instance using mcpServers.

src/mastra/index.ts
import { Mastra } from "@mastra/core/mastra";

import { testMcpServer } from "./mcp/test-mcp-server";

export const mastra = new Mastra({
  // ...
  mcpServers: { testMcpServer },
});

Static and dynamic tools​

MCPClient offers two approaches to retrieving tools from connected servers, suitable for different application architectures:

FeatureStatic Configuration (await mcp.getTools())Dynamic Configuration (await mcp.getToolsets())
Use CaseSingle-user, static config (e.g., CLI tool)Multi-user, dynamic config (e.g., SaaS app)
ConfigurationFixed at agent initializationPer-request, dynamic
CredentialsShared across all usesCan vary per user/request
Agent SetupTools added in Agent constructorTools passed in .generate() or .stream() options

Static tools​

Use the .getTools() method to fetch tools from all configured MCP servers. This is suitable when configuration (such as API keys) is static and consistent across users or requests. Call it once and pass the result to the tools property when defining your agent.

See getTools() for more information.

src/mastra/agents/test-agent.ts
import { openai } from "@ai-sdk/openai";
import { Agent } from "@mastra/core/agent";

import { testMcpClient } from "../mcp/test-mcp-client";

export const testAgent = new Agent({
  // ...
  tools: await testMcpClient.getTools(),
});

Dynamic tools​

Use the .getToolsets() method when tool configuration may vary by request or user, such as in a multi-tenant system where each user provides their own API key. This method returns toolsets that can be passed to the toolsets option in the agent's .generate() or .stream() calls.

import { MCPClient } from "@mastra/mcp";
import { mastra } from "./mastra";

async function handleRequest(userPrompt: string, userApiKey: string) {
  const userMcp = new MCPClient({
    servers: {
      weather: {
        url: new URL("http://localhost:8080/mcp"),
        requestInit: {
          headers: {
            Authorization: `Bearer ${userApiKey}`,
          },
        },
      },
    },
  });

  const agent = mastra.getAgent("testAgent");

  const response = await agent.generate(userPrompt, {
    toolsets: await userMcp.getToolsets(),
  });

  await userMcp.disconnect();

  return Response.json({
    data: response.text,
  });
}

See getToolsets() for more information.

Connecting to an MCP registry​

MCP servers can be discovered through registries. Here's how to connect to some popular ones using MCPClient:

Klavis AI provides hosted, enterprise-authenticated, high-quality MCP servers.

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 offers enterprise-grade authentication and security for production deployments.

For more details on how to integrate Mastra with Klavis, check out their documentation.