Skip to main content
The MastraAdapter converts MCP tools into the format expected by the Mastra framework. Each tool is returned as an entry in a Record<string, MastraTool> object, where every value carries an id, a description, a Zod inputSchema, and an execute function that calls the corresponding MCP tool.

​
Installation

npm install @mcp-ts/sdk zod
zod is a required peer dependency. The adapter uses it internally to build the inputSchema for each tool. You do not need to install the Mastra SDK itself to use the adapter — the tool shape matches the Mastra interface so Mastra can consume it at runtime.

​
Quick start

import { MultiSessionClient } from '@mcp-ts/sdk/server';
import { MastraAdapter } from '@mcp-ts/sdk/adapters/mastra';

const client = new MultiSessionClient('user_123');
await client.connect();

const tools = await MastraAdapter.getTools(client);

​
API reference

​
new MastraAdapter(client, options?)

Creates an adapter instance. Zod is loaded lazily on the first call to getTools().
ParameterTypeDescription
clientMCPClient | MultiSessionClientThe MCP client to source tools from.
optionsMastraAdapterOptionsOptional configuration (see below).

​
adapter.getTools()

Fetches the tool list from all connected MCP servers and returns a Promise<Record<string, MastraTool>>. The key for each entry is the namespaced tool name (<prefix>_<toolName>). When the underlying client is not connected, getTools() returns an empty object {} instead of throwing.

​
MastraAdapter.getTools(client, options?) (static)

A convenience wrapper that creates a MastraAdapter and immediately calls getTools(). 
const tools = await MastraAdapter.getTools(client, { prefix: 'myapp' });

​
MastraAdapterOptions

FieldTypeDefaultDescription
prefixstringServer ID (8 chars)Namespace prefix prepended to every tool name.

​
MastraTool shape

Each value in the returned record conforms to the following interface: 
interface MastraTool {
  id: string;                         // Namespaced tool name
  description: string;                // MCP tool description
  inputSchema: z.ZodType<any>;        // Zod schema derived from JSON Schema
  execute: (args: any) => Promise<any>; // Calls client.callTool(toolName, args)
}

​
Complete agent example

1

Connect to MCP servers

Create a MultiSessionClient and call connect() to establish sessions with your configured MCP servers.
import { MultiSessionClient } from '@mcp-ts/sdk/server';

const client = new MultiSessionClient('user_123');
await client.connect();
2

Fetch tools with MastraAdapter

Use the static getTools method to retrieve all MCP tools in Mastra-compatible format.
import { MastraAdapter } from '@mcp-ts/sdk/adapters/mastra';

const tools = await MastraAdapter.getTools(client);
3

Pass tools to a Mastra Agent

Spread the tool record directly into your Mastra Agent configuration.
import { Agent } from '@mastra/core';
import { openai } from '@ai-sdk/openai';

const agent = new Agent({
  name: 'mcp-agent',
  instructions: 'You are a helpful assistant with access to external tools.',
  model: openai('gpt-4o'),
  tools,
});

const response = await agent.generate('What files are in the current directory?');
console.log(response.text);

​
Tool naming

Tool names follow the pattern <prefix>_<toolName>. The prefix defaults to the first eight characters of the server ID with hyphens removed. 
abcd1234_list_files
abcd1234_read_file
Set an explicit prefix to control the namespace: 
const tools = await MastraAdapter.getTools(client, { prefix: 'fs' });
// fs_list_files, fs_read_file, …

​
Using with MultiSessionClient

When you pass a MultiSessionClient, the adapter queries all connected servers concurrently and merges the results into a single flat record. If a server fails to respond, its tools are skipped with a console error and the remaining tools are returned. 
const client = new MultiSessionClient('user_123');
await client.connect();

// Collects tools from every connected server
const tools = await MastraAdapter.getTools(client);
If two connected MCP servers expose a tool with the same name, the last one fetched will overwrite earlier entries in the result record. Use the prefix option to ensure uniqueness when connecting to multiple servers with overlapping tool names.

​
Disconnected clients

If client.isConnected() returns false when getTools() is called, the adapter returns {} immediately. No error is thrown — the Mastra agent simply has no tools available for that session. 
const adapter = new MastraAdapter(client);
const tools = await adapter.getTools();
// {} if client is not connected