Skip to Content
DocsAgentsUsing MCP

Using MCP With Mastra

Model Context Protocol (MCP)  is a standardized way for AI models to discover and interact with external tools and resources.

Overview

MCP in Mastra provides a standardized way to connect to tool servers and supports both stdio and SSE-based connections.

Installation

Using pnpm:

pnpm add @mastra/mcp@latest

Using npm:

npm install @mastra/mcp@latest

Using MCP in Your Code

The MCPConfiguration class provides a way to manage multiple tool servers in your Mastra applications without managing multiple MCP clients. You can configure both stdio-based and SSE-based servers:

import { MCPConfiguration } from "@mastra/mcp";
import { Agent } from "@mastra/core/agent";
import { openai } from "@ai-sdk/openai";
 
const mcp = new MCPConfiguration({
  servers: {
    // stdio example
    sequential: {
      name: "sequential-thinking",
      server: {
        command: "npx",
        args: ["-y", "@modelcontextprotocol/server-sequential-thinking"],
      },
    },
    // SSE example
    weather: {
      url: new URL("http://localhost:8080/sse"),
      requestInit: {
        headers: {
          Authorization: "Bearer your-token",
        },
      },
    },
  },
});

Tools vs Toolsets

The MCPConfiguration class provides two ways to access MCP tools, each suited for different use cases:

Using Tools (getTools())

Use this approach when:

  • You have a single MCP connection
  • The tools are used by a single user/context
  • Tool configuration (API keys, credentials) remains constant
  • You want to initialize an Agent with a fixed set of tools
const agent = new Agent({
  name: "CLI Assistant",
  instructions: "You help users with CLI tasks",
  model: openai("gpt-4o-mini"),
  tools: await mcp.getTools(), // Tools are fixed at agent creation
});

Using Toolsets (getToolsets())

Use this approach when:

  • You need per-request tool configuration
  • Tools need different credentials per user
  • Running in a multi-user environment (web app, API, etc)
  • Tool configuration needs to change dynamically
const mcp = new MCPConfiguration({
  servers: {
    example: {
      command: "npx",
      args: ["-y", "@example/fakemcp"],
      env: {
        API_KEY: "your-api-key",
      },
    },
  },
});
 
// Get the current toolsets configured for this user
const toolsets = await mcp.getToolsets();
 
// Use the agent with user-specific tool configurations
const response = await agent.stream(
  "What's new in Mastra and how's the weather?",
  {
    toolsets,
  },
);

MCP Registries

MCP servers can be accessed through registries that provide curated collections of tools. We’ve curated an MCP Registry Registry  to help you find the best places to source MCP servers, but here’s how you can use tools from some of our favorites:

mcp.run Registry

mcp.run  makes it easy for you to call pre-authenticated, secure MCP Servers. The tools from mcp.run are free, and entirely managed, so your agent only needs a SSE URL and can use any tools a user has installed. MCP Servers are grouped into Profiles , and accessed with a unique SSE URL.

For each Profile, you can copy/paste unique, signed URLs into your MCPConfiguration like this:

const mcp = new MCPConfiguration({
  servers: {
    marketing: {
      url: new URL(process.env.MCP_RUN_SSE_URL!),
    },
  },
});

Important: Each SSE URL on on mcp.run  contains a unique signature, that should be treated like a password. It’s best to read your SSE URL as an environment variable and manage it outside of your application code.

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

Composio.dev Registry

Composio.dev  provides a registry of SSE-based MCP servers  that can be easily integrated with Mastra. The SSE URL that’s generated for Cursor is compatible with Mastra - you can use it directly in your configuration:

const mcp = new MCPConfiguration({
  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]"),
    },
  },
});

When using Composio-provided tools, you can authenticate with services (like Google Sheets or Gmail) directly through conversation with your agent. The tools include authentication capabilities that guide you through the process while chatting.

Note: The Composio.dev integration is best suited for single-user scenarios like personal automation, as the SSE URL is tied to your account and can’t be used for multiple users. Each URL represents a single account’s authentication context.

Smithery.ai Registry

Smithery.ai  provides a registry of MCP servers that you can easily use with Mastra:

// 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",
        "{}",
      ],
    },
  },
});

This example is adapted from the Claude integration example in the Smithery documentation.

Using the Mastra Documentation Server

Looking to use Mastra’s MCP documentation server in your IDE? Check out our MCP Documentation Server guide to get started.

Next Steps

Adding ToolsAdding Voice