Skip to content
Live
Mastra Blog·· 2 days ago

Introducing Mastra's Built-in MCP Server

Introducing Mastra's Built-in MCP Server

Brief overview

Mastra has added a built-in MCP server. After installing @mastra/mcp and configuring authentication, proxies, workflows, and tools can be exposed at /api/mcp, supporting operations such as _agent, start_workflow, and get_trace.

Article

You can now expose your agents, workflows, and tools to MCP using the new built-in MCP server. Install @mastra/mcp, configure auth, and your whole Mastra server becomes available at /api/mcp.

The MCP server comes equipped with tools to call_agent, start_workflow, and get_trace. Configured coding agents, or connected MCP clients, can then handle tasks you'd normally do yourself using the Studio UI.

This release builds on our existing MCP 2.0 support, and joins MCP tasks and MCP events as the latest addition to Mastra's MCP server and client capabilities.

Requests will typically require a bearer token, verified by your auth provider. Each MCP tool call uses the same server routes as standard HTTP requests, and goes through the same RBAC and FGA checks (if configured). You can also choose which agents, workflows, and tools the MCP server exposes.

Get started

Install the following packages, this example uses Mastra platform auth. Any supported auth provider will also work:

npm install @mastra/core@latest @mastra/mcp@latest @mastra/auth-studio@latest

note

Requires @mastra/[email protected] or later, added in PR #29929.

Configure auth

Configure an auth provider on your main Mastra instance to expose the MCP server at <server-url>/api/mcp:

import { MastraAuthStudio } from "@mastra/auth-studio";
 
export const mastra = new Mastra({
  // ...
  server: {
    auth: new MastraAuthStudio({
      organizationId: process.env.MASTRA_ORGANIZATION_ID
    })
  }
});

In production, if an auth provider isn't configured, Mastra won't expose the MCP server, but you can override this using enabled: true:

export const mastra = new Mastra({
  // ...
  server: {
    mcp: {
      enabled: true
    }
  }
});

Choose what to expose

For tighter control over what to expose, use toolsets, include, and exclude to choose specific agents, workflows, or tools:

export const mastra = new Mastra({
  // ...
  server: {
    mcp: {
      toolsets: ["agents", "tools"],
      include: { agents: ["support-agent", "billing-agent"] },
      exclude: { tools: ["delete-account"] }
    }
  }
});

Connect Claude Code

Once you've configured and deployed your Mastra project, you can connect it to Claude Code using mcp add, followed by the server URL and an authorization token:

claude mcp add --transport http sit-rep <server-url>/api/mcp --header "Authorization: Bearer <token>"

Chat to your Mastra server

After you've added the MCP server to Claude Code's config, you can call your agents, run workflows and tools, and read memory or traces:

Run the docs-sync-workflow

For more information and full configuration options, see:

Source: Mastra Blog · mastra.ai