@mastra/mcp

Model Context Protocol (MCP) client implementation for Mastra, providing seamless integration with MCP-compatible AI models and tools.

Installation

npm install @mastra/mcp

Overview

The @mastra/mcp package provides a client implementation for the Model Context Protocol (MCP), enabling Mastra to communicate with MCP-compatible AI models and tools. It wraps the official @modelcontextprotocol/sdk and provides Mastra-specific functionality.

Usage

import { MastraMCPClient } from '@mastra/mcp';

// Create a client with stdio server
const stdioClient = new MastraMCPClient({
  name: 'my-stdio-client',
  version: '1.0.0', // optional
  server: {
    command: 'your-mcp-server-command',
    args: ['--your', 'args'],
  },
  capabilities: {}, // optional ClientCapabilities
});

// Or create a client with SSE server
const sseClient = new MastraMCPClient({
  name: 'my-sse-client',
  version: '1.0.0',
  server: {
    url: new URL('https://your-mcp-server.com/sse'),
    requestInit: {
      headers: { Authorization: 'Bearer your-token' },
    },
    eventSourceInit: {
      fetch(input: Request | URL | string, init?: RequestInit) {
        const headers = new Headers(init?.headers || {});
        headers.set('Authorization', 'Bearer your-token');
        return fetch(input, {
          ...init,
          headers,
        });
      },
    },
  },
  timeout: 60000, // optional timeout for tool calls in milliseconds
});

// Connect to the MCP server
await client.connect();

// List available resources
const resources = await client.resources();

// Get available tools
const tools = await client.tools();

// Disconnect when done
await client.disconnect();

Managing Multiple MCP Servers

For applications that need to interact with multiple MCP servers, the MCPConfiguration class provides a convenient way to manage multiple server connections and their tools:

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

const mcp = new MCPConfiguration({
  servers: {
    // Stdio-based server
    stockPrice: {
      command: 'npx',
      args: ['tsx', 'stock-price.ts'],
      env: {
        API_KEY: 'your-api-key',
      },
    },
    // SSE-based server
    weather: {
      url: new URL('http://localhost:8080/sse'),
    },
  },
});

// Get all tools from all configured servers namespaced with the server name
const tools = await mcp.getTools();

// Get tools grouped into a toolset object per-server
const toolsets = await mcp.getToolsets();

Logging

The MCP client provides per-server logging capabilities, allowing you to monitor interactions with each MCP server separately:

import { MCPConfiguration, LogMessage, LoggingLevel } from '@mastra/mcp';

// Define a custom log handler
const weatherLogger = (logMessage: LogMessage) => {
  console.log(`[${logMessage.level}] ${logMessage.serverName}: ${logMessage.message}`);

  // Log data contains valuable information
  console.log('Details:', logMessage.details);
  console.log('Timestamp:', logMessage.timestamp);
};

// Initialize MCP configuration with server-specific loggers
const mcp = new MCPConfiguration({
  servers: {
    weatherService: {
      command: 'npx',
      args: ['tsx', 'weather-mcp.ts'],
      // Attach the logger to this specific server
      log: weatherLogger,
    },

    stockPriceService: {
      command: 'npx',
      args: ['tsx', 'stock-mcp.ts'],
      // Different logger for this service
      log: logMessage => {
        // Just log errors and critical events for this service
        if (['error', 'critical', 'alert', 'emergency'].includes(logMessage.level)) {
          console.error(`Stock service ${logMessage.level}: ${logMessage.message}`);
        }
      },
    },
  },
});

Log Message Structure

Each log message contains the following information:

interface LogMessage {
  level: LoggingLevel; // MCP SDK standard log levels
  message: string;
  timestamp: Date;
  serverName: string;
  details?: Record<string, any>;
}

The LoggingLevel type is directly imported from the MCP SDK, ensuring compatibility with all standard MCP log levels: 'debug' | 'info' | 'notice' | 'warning' | 'error' | 'critical' | 'alert' | 'emergency'.

Creating Reusable Loggers

You can create reusable logger factories for common patterns:

// File logger factory with color coded output for different severity levels
const createFileLogger = filePath => {
  return logMessage => {
    // Format the message based on level
    const prefix =
      logMessage.level === 'emergency' ? '!!! EMERGENCY !!! ' : logMessage.level === 'alert' ? '! ALERT ! ' : '';

    // Write to file with timestamp, level, etc.
    fs.appendFileSync(
      filePath,
      `[${logMessage.timestamp.toISOString()}] [${logMessage.level.toUpperCase()}] ${prefix}${logMessage.message}\n`,
    );
  };
};

// Use the factory in configuration
const mcp = new MCPConfiguration({
  servers: {
    weatherService: {
      command: 'npx',
      args: ['tsx', 'weather-mcp.ts'],
      log: createFileLogger('./logs/weather.log'),
    },
  },
});

See the examples/server-logging.ts file for comprehensive examples of various logging strategies.

Tools vs Toolsets

The MCPConfiguration class provides two ways to access MCP tools:

Tools (getTools())

Use this when:

• You have a single MCP connection
• The tools are used by a single user/context (CLI tools, automation scripts, etc)
• 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-4'),
  tools: await mcp.getTools(), // Tools are fixed at agent creation
});

Toolsets (getToolsets())

Use this 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

import { MCPConfiguration } from '@mastra/mcp';
import { Agent } from '@mastra/core/agent';
import { openai } from '@ai-sdk/openai';

// Configure MCP servers with user-specific settings before getting toolsets
const mcp = new MCPConfiguration({
  servers: {
    stockPrice: {
      command: 'npx',
      args: ['tsx', 'weather-mcp.ts'],
      env: {
        // These would be different per user
        API_KEY: 'user-1-api-key',
      },
    },
    weather: {
      url: new URL('http://localhost:8080/sse'),
      requestInit: {
        headers: {
          // These would be different per user
          Authorization: 'Bearer user-1-token',
        },
      },
      eventSourceInit: {
        fetch(input: Request | URL | string, init?: RequestInit) {
          const headers = new Headers(init?.headers || {});
          headers.set('Authorization', 'Bearer user-1-token');
          return fetch(input, {
            ...init,
            headers,
          });
        },
      },
    },
  },
});

// 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.generate('What is the weather in London?', {
  toolsets,
});

console.log(response.text);

The MCPConfiguration class automatically:

• Manages connections to multiple MCP servers
• Namespaces tools to prevent naming conflicts
• Handles connection lifecycle and cleanup
• Provides both flat and grouped access to tools

SSE Authentication and Headers

When using SSE (Server-Sent Events) connections with authentication or custom headers, you need to configure headers in a specific way. The standard requestInit headers won't work alone because SSE connections use the browser's EventSource API, which doesn't support custom headers directly.

The eventSourceInit configuration allows you to customize the underlying fetch request used for the SSE connection, ensuring your authentication headers are properly included.

To properly include authentication headers or other custom headers in SSE connections, you need to use both requestInit and eventSourceInit:

const sseClient = new MastraMCPClient({
  name: 'authenticated-sse-client',
  server: {
    url: new URL('https://your-mcp-server.com/sse'),
    // requestInit alone isn't enough for SSE connections
    requestInit: {
      headers: { Authorization: 'Bearer your-token' },
    },
    // eventSourceInit is required to include headers in the SSE connection
    eventSourceInit: {
      fetch(input: Request | URL | string, init?: RequestInit) {
        const headers = new Headers(init?.headers || {});
        headers.set('Authorization', 'Bearer your-token');
        return fetch(input, {
          ...init,
          headers,
        });
      },
    },
  },
});

This configuration ensures that:

1. The authentication headers are properly included in the SSE connection request
2. The connection can be established with the required credentials
3. Subsequent messages can be received through the authenticated connection

Configuration

Required Parameters

• name: Name of the MCP client instance

• server: Either a StdioServerParameters or SSEClientParameters object:

  StdioServerParameters

  • command: Command to start the MCP server
  • args: Array of command arguments

  SSEClientParameters

  • url: URL instance pointing to the SSE server
  • requestInit: Optional fetch request configuration
  • eventSourceInit: Optional EventSource configuration

Optional Parameters

• version: Client version (default: '1.0.0')
• capabilities: ClientCapabilities object for specifying supported features
• log: Function that receives and processes log messages

Features

• Standard MCP client implementation
• Automatic tool conversion to Mastra format
• Resource discovery and management
• Multiple transport layers:
  • Stdio-based for local servers
  • SSE-based for remote servers
• Per-server logging capability using all standard MCP log levels
• Automatic error handling and logging
• Tool execution with context

Methods

connect()

Establishes connection with the MCP server.

disconnect()

Closes the connection with the MCP server.

resources()

Lists available resources from the MCP server.

tools()

Retrieves and converts MCP tools to Mastra-compatible format.

Tool Conversion

The package automatically converts MCP tools to Mastra's format:

const tools = await client.tools();
// Returns: { [toolName: string]: MastraTool }

// Each tool includes:
// - Converted JSON schema
// - Mastra-compatible execution wrapper
// - Error handling
// - Automatic context passing

Error Handling

The client includes comprehensive error handling:

• Connection errors
• Tool execution errors
• Resource listing errors
• Schema conversion errors

Related Links

• Model Context Protocol Specification
• @modelcontextprotocol/sdk Documentation