Skip to Content
ReferenceToolsMCPServer

MCPServer

The MCPServer class provides the functionality to expose your existing Mastra tools as a Model Context Protocol (MCP) server. This allows any MCP client (like Cursor, Windsurf, or Claude Desktop) to connect to the tools and make them available to an agent. Note that if you only need to use your tools in your Mastra agents you don’t need to create an MCP server. This API allows you to expose your Mastra tools to external MCP clients. In Mastra you can use your tools directly without MCP.

It supports both stdio (subprocess) and SSE (HTTP) MCP transports .

Properties

To create a new MCPServer, you need to provide some basic information about your server and the tools it will offer.

name:

string
A name for your server (like 'My Weather Server').

version:

string
The version of your server (like '1.0.0').

tools:

ToolsInput
An object containing the tools you want to make available. This can include tools created with Mastra or the Vercel AI SDK.

For example, here’s how you might create a new MCPServer instance:

import { MCPServer } from "@mastra/mcp";
import { weatherTool } from "./tools"; // Assuming you have a weather tool defined in this file
 
const server = new MCPServer({
  name: "My Weather Server",
  version: "1.0.0",
  tools: { weatherTool },
});

Methods

These are the functions you can call on an MCPServer instance to control its behavior and get information.

startStdio()

Use this method to start the server so it communicates using standard input and output (stdio). This is typical when running the server as a command-line program.

async startStdio(): Promise<void>

Here’s how you would start the server using stdio:

const server = new MCPServer({
  // example configuration above
});
await server.startStdio();

startSSE()

This method helps you integrate the MCP server with an existing web server to use Server-Sent Events (SSE) for communication. You’ll call this from your web server’s code when it receives a request for the SSE or message paths.

async startSSE({
  url,
  ssePath,
  messagePath,
  req,
  res,
}: {
  url: URL;
  ssePath: string;
  messagePath: string;
  req: any;
  res: any;
}): Promise<void>

Here’s an example of how you might use startSSE within an HTTP server request handler. In this example an MCP client could connect to your MCP server at http://localhost:1234/sse:

import http from "http";
 
const httpServer = http.createServer(async (req, res) => {
  await server.startSSE({
    url: new URL(req.url || "", `http://localhost:1234`),
    ssePath: "/sse",
    messagePath: "/message",
    req,
    res,
  });
});
 
httpServer.listen(PORT, () => {
  console.log(`HTTP server listening on port ${PORT}`);
});

Here are the details for the values needed by the startSSE method:

url:

URL
The web address the user is requesting.

ssePath:

string
The specific part of the URL where clients will connect for SSE (e.g., '/sse').

messagePath:

string
The specific part of the URL where clients will send messages (e.g., '/message').

req:

any
The incoming request object from your web server.

res:

any
The response object from your web server, used to send data back.

getStdioTransport()

If you started the server with startStdio(), you can use this to get the object that manages the stdio communication. This is mostly for checking things internally or for testing.

getStdioTransport(): StdioServerTransport | undefined

getSseTransport()

If you started the server with startSSE(), you can use this to get the object that manages the SSE communication. Like getStdioTransport, this is mainly for internal checks or testing.

getSseTransport(): SSEServerTransport | undefined

tools()

This method gives you a look at the tools that were set up when you created the server. It’s a read-only list, useful for debugging purposes.

tools(): Readonly<Record<string, ConvertedTool>>

Examples

For practical examples of setting up and deploying an MCPServer, see the Deploying an MCPServer Example.

MCPConfigurationWorkflow