Skip to Content
ReferenceToolsMCPConfiguration

MCPConfiguration

The MCPConfiguration class provides a way to manage multiple MCP server connections and their tools in a Mastra application. It handles connection lifecycle, tool namespacing, and provides convenient access to tools across all configured servers.

Constructor

Creates a new instance of the MCPConfiguration class.

constructor({
  id?: string;
  servers: Record<string, MastraMCPServerDefinition>;
  timeout?: number;
}: MCPConfigurationOptions)

MCPConfigurationOptions


id?:

string
Optional unique identifier for the configuration instance. Use this to prevent memory leaks when creating multiple instances with identical configurations.

servers:

Record<string, MastraMCPServerDefinition>
A map of server configurations, where each key is a unique server identifier and the value is the server configuration.

timeout?:

number
= 60000
Global timeout value in milliseconds for all servers unless overridden in individual server configs.

MastraMCPServerDefinition

Each server in the servers map can be configured as either a stdio-based server or an SSE-based server. For details about the available configuration options, see MastraMCPServerDefinition in the MastraMCPClient documentation.

Methods

getTools()

Retrieves all tools from all configured servers, with tool names namespaced by their server name (in the format serverName_toolName) to prevent conflicts. Intended to be passed onto an Agent definition.

new Agent({ tools: await mcp.getTools() });

getToolsets()

Returns an object mapping namespaced tool names (in the format serverName.toolName) to their tool implementations. Intended to be passed dynamically into the generate or stream method.

const res = await agent.stream(prompt, {
  toolsets: await mcp.getToolsets(),
});

disconnect()

Disconnects from all MCP servers and cleans up resources.

async disconnect(): Promise<void>

Examples

Basic Usage

import { MCPConfiguration } from "@mastra/mcp";
import { Agent } from "@mastra/core/agent";
import { openai } from "@ai-sdk/openai";
 
const mcp = new MCPConfiguration({
  servers: {
    stockPrice: {
      command: "npx",
      args: ["tsx", "stock-price.ts"],
      env: {
        API_KEY: "your-api-key",
      },
      log: (logMessage) => {
        console.log(`[${logMessage.level}] ${logMessage.message}`);
      },
    },
    weather: {
      url: new URL("http://localhost:8080/sse"),∂
    },
  },
  timeout: 30000, // Global 30s timeout
});
 
// Create an agent with access to all tools
const agent = new Agent({
  name: "Multi-tool Agent",
  instructions: "You have access to multiple tool servers.",
  model: openai("gpt-4"),
  tools: await mcp.getTools(),
});

Using Toolsets in generate() or stream()

import { Agent } from "@mastra/core/agent";
import { MCPConfiguration } from "@mastra/mcp";
import { openai } from "@ai-sdk/openai";
 
// Create the agent first, without any tools
const agent = new Agent({
  name: "Multi-tool Agent",
  instructions: "You help users check stocks and weather.",
  model: openai("gpt-4"),
});
 
// Later, configure MCP with user-specific settings
const mcp = new MCPConfiguration({
  servers: {
    stockPrice: {
      command: "npx",
      args: ["tsx", "stock-price.ts"],
      env: {
        API_KEY: "user-123-api-key",
      },
      timeout: 20000, // Server-specific timeout
    },
    weather: {
      url: new URL("http://localhost:8080/sse"),
      requestInit: {
        headers: {
          Authorization: `Bearer user-123-token`,
        },
      },
    },
  },
});
 
// Pass all toolsets to stream() or generate()
const response = await agent.stream(
  "How is AAPL doing and what is the weather?",
  {
    toolsets: await mcp.getToolsets(),
  },
);

Resource Management

The MCPConfiguration class includes built-in memory leak prevention for managing multiple instances:

  1. Creating multiple instances with identical configurations without an id will throw an error to prevent memory leaks
  2. If you need multiple instances with identical configurations, provide a unique id for each instance
  3. Call await configuration.disconnect() before recreating an instance with the same configuration
  4. If you only need one instance, consider moving the configuration to a higher scope to avoid recreation

For example, if you try to create multiple instances with the same configuration without an id:

// First instance - OK
const mcp1 = new MCPConfiguration({
  servers: {
    /* ... */
  },
});
 
// Second instance with same config - Will throw an error
const mcp2 = new MCPConfiguration({
  servers: {
    /* ... */
  },
});
 
// To fix, either:
// 1. Add unique IDs
const mcp3 = new MCPConfiguration({
  id: "instance-1",
  servers: {
    /* ... */
  },
});
 
// 2. Or disconnect before recreating
await mcp1.disconnect();
const mcp4 = new MCPConfiguration({
  servers: {
    /* ... */
  },
});

Server Lifecycle

MCPConfiguration handles server connections gracefully:

  1. Automatic connection management for multiple servers
  2. Graceful server shutdown to prevent error messages during development
  3. Proper cleanup of resources when disconnecting
MastraMCPClientMCPServer