MCP server Mastra integration

Mastra architecture for MCP

Mastra structures agent applications around three primitives:

The separation between MCPConfiguration (static spec) and Toolset (live connection) means you can define server endpoints once at startup and obtain fresh tool lists per-agent-invocation or per-workflow-step.

MCPConfiguration setup

Define all MCP server connections in a single MCPConfiguration object. Mastra supports both stdio (subprocess) and HTTP/SSE transport:

import { MCPConfiguration } from "@mastra/mcp";
import { Agent, createAgent } from "@mastra/core";
import Anthropic from "@anthropic-ai/sdk";

// Define all MCP servers once
const mcpConfig = new MCPConfiguration({
  servers: {
    // HTTP/SSE transport — production remote MCP server
    search: {
      url: new URL(process.env.SEARCH_MCP_URL!),
      requestInit: {
        headers: { Authorization: `Bearer ${process.env.SEARCH_MCP_TOKEN}` },
      },
    },
    // stdio transport — local MCP server (development)
    database: {
      command: "node",
      args: ["./db-server/build/index.js"],
      env: {
        DATABASE_URL: process.env.DATABASE_URL!,
      },
    },
    // HTTP/SSE with custom timeout
    codeExecution: {
      url: new URL(process.env.CODE_MCP_URL!),
      requestInit: {
        headers: { Authorization: `Bearer ${process.env.CODE_MCP_TOKEN}` },
        signal: AbortSignal.timeout(30_000),  // 30 s per tool call
      },
    },
  },
});

The servers keys become the namespace prefix for tools from each server. When the search server exposes a tool named search_web, Mastra makes it available as search_search_web to avoid name collisions across servers. You can override name prefixing in advanced configurations.

Creating an agent with MCP tools

Pass a toolset from MCPConfiguration to createAgent. The toolset is obtained asynchronously — it connects to MCP servers and calls tools/list — so it must be awaited before the agent is constructed:

const anthropic = new Anthropic({ apiKey: process.env.ANTHROPIC_API_KEY });

async function buildResearchAgent(): Promise {
  // getToolset() connects to all configured MCP servers and discovers their tools
  const toolset = await mcpConfig.getToolset();

  const agent = createAgent({
    name: "ResearchAgent",
    instructions: `You are a research agent with access to a live web search and database.
    - Use search tools to find current information and recent publications.
    - Use database tools to query structured data.
    - Cite sources in your responses.
    - Prefer specific queries over broad ones — narrow searches return better results.`,
    model: {
      provider: "ANTHROPIC",
      name: "claude-sonnet-4-6",
      toolChoice: "auto",
    },
    tools: {
      toolsets: [toolset],
    },
  });

  return agent;
}

// Usage
const agent = await buildResearchAgent();
const response = await agent.generate(
  "What MCP servers have the highest uptime according to recent registry scans?",
);
console.log(response.text);

toolChoice: "auto" lets the model decide when to call tools. Use "required" to force at least one tool call per turn (useful for workflows that must retrieve data before answering) or { type: "tool", toolName: "search_search_web" } to force a specific tool on the first turn.

Workflow steps with MCP tools

Mastra workflows define typed step-by-step execution. Each step can obtain its own MCP toolset, use it, and pass results to the next step through the workflow's typed state:

import { createWorkflow, createStep } from "@mastra/core/workflows";
import { z } from "zod";

const researchWorkflow = createWorkflow({
  id: "mcp-research-pipeline",
  inputSchema: z.object({ topic: z.string() }),
  outputSchema: z.object({ report: z.string(), sources: z.array(z.string()) }),
})
  .addStep(
    createStep({
      id: "gather-sources",
      inputSchema: z.object({ topic: z.string() }),
      outputSchema: z.object({ rawResults: z.string(), urls: z.array(z.string()) }),
      async execute({ inputData }) {
        // Get a fresh toolset scoped to this step
        const toolset = await mcpConfig.getToolset();
        const tools = toolset.getTools();

        const searchTool = tools.find((t) => t.name === "search_search_web");
        if (!searchTool) throw new Error("search_web tool not found on MCP server");

        const result = await searchTool.execute({ query: inputData.topic, max_results: 10 });
        const parsed = JSON.parse(result.text ?? "[]");
        return {
          rawResults: result.text ?? "",
          urls: parsed.map((r: { url: string }) => r.url),
        };
      },
    }),
  )
  .addStep(
    createStep({
      id: "synthesize-report",
      inputSchema: z.object({ rawResults: z.string(), urls: z.array(z.string()) }),
      outputSchema: z.object({ report: z.string(), sources: z.array(z.string()) }),
      async execute({ inputData }) {
        const agent = await buildResearchAgent();
        const response = await agent.generate(
          `Synthesize this research into a structured report: ${inputData.rawResults}`,
        );
        return { report: response.text, sources: inputData.urls };
      },
    }),
  );

// Run the workflow
const result = await researchWorkflow
  .createRun()
  .start({ inputData: { topic: "MCP server security vulnerabilities 2026" } });

Each step calls mcpConfig.getToolset() independently, which keeps MCP connections short-lived and scoped to each step's execution. This is safer than sharing a single long-lived toolset across all steps: if a step fails and is retried, it gets a fresh connection rather than inheriting a potentially broken one.

Tool execution hooks for monitoring

Mastra exposes lifecycle hooks on agents for observability. Use these to track MCP tool call latency and error rates without modifying tool implementations:

import { createAgent } from "@mastra/core";

const agent = createAgent({
  name: "MonitoredResearchAgent",
  // ...other config...
  hooks: {
    onToolCall: async ({ toolName, input, startTime }) => {
      console.log(`[MCP] Calling tool: ${toolName}`, { input });
    },
    onToolResult: async ({ toolName, result, startTime }) => {
      const latencyMs = Date.now() - startTime;
      console.log(`[MCP] Tool ${toolName} completed in ${latencyMs}ms`, {
        isError: result?.isError,
        latencyMs,
      });
      // Emit to your metrics system (Datadog, OpenTelemetry, etc.)
      metrics.histogram("mcp.tool.latency", latencyMs, { tool: toolName });
      if (result?.isError) {
        metrics.increment("mcp.tool.error", { tool: toolName });
      }
    },
    onToolError: async ({ toolName, error, startTime }) => {
      const latencyMs = Date.now() - startTime;
      console.error(`[MCP] Tool ${toolName} failed after ${latencyMs}ms:`, error.message);
      metrics.increment("mcp.tool.exception", { tool: toolName });
    },
  },
});

These hooks fire on every tool call including MCP tool calls. The startTime parameter is a timestamp in milliseconds captured before the tool call begins, enabling precise latency measurement even for concurrent tool calls.

Monitoring MCP servers in Mastra deployments

Mastra agents are typically deployed as HTTP API servers (via @mastra/server) or serverless functions. In both cases, MCP server failures appear as tool errors in agent responses — the agent's final text might say "I was unable to retrieve that information" without any indication that the underlying MCP server is down.

Add a startup health check and run AliveMCP continuous monitoring:

import { MCPConfiguration } from "@mastra/mcp";

async function healthCheckMCPServers(config: MCPConfiguration): Promise {
  const toolset = await config.getToolset();
  const tools = toolset.getTools();

  if (tools.length === 0) {
    throw new Error(
      "MCP health check failed: no tools discovered. " +
      "Check that all configured MCP servers are reachable."
    );
  }

  console.log(`MCP health check passed: ${tools.length} tools discovered across all servers`);
  await config.disconnect();  // close the probe connection
}

// At app startup, before accepting requests
await healthCheckMCPServers(mcpConfig).catch((err) => {
  console.error("MCP preflight failed — aborting startup:", err.message);
  process.exit(1);
});

The preflight calls getToolset(), which connects to all configured MCP servers, then checks that at least one tool was discovered. Failing fast at startup is far better than silently serving responses that omit MCP-sourced data. Complement this with continuous monitoring via AliveMCP so you detect servers that go down after your service started.

Further reading

• MCP server LangChain integration — using MCP tools in LangChain agents
• MCP server LlamaIndex integration — using MCP tools in LlamaIndex agents
• MCP server authentication — API keys, bearer tokens, and OAuth 2.0
• MCP server health check — designing a robust /health endpoint
• MCP server uptime monitoring — continuous availability checking
• AliveMCP — continuous protocol monitoring for MCP servers