@mastra/mcp 1.0.1 → 1.0.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (14) hide show
  1. package/CHANGELOG.md +22 -0
  2. package/dist/client/client.d.ts.map +1 -1
  3. package/dist/docs/SKILL.md +1 -1
  4. package/dist/docs/assets/SOURCE_MAP.json +1 -1
  5. package/dist/docs/references/docs-mcp-overview.md +81 -78
  6. package/dist/docs/references/docs-mcp-publishing-mcp-server.md +15 -15
  7. package/dist/docs/references/reference-tools-mcp-client.md +223 -231
  8. package/dist/docs/references/reference-tools-mcp-server.md +280 -284
  9. package/dist/index.cjs +34 -18
  10. package/dist/index.cjs.map +1 -1
  11. package/dist/index.js +28 -12
  12. package/dist/index.js.map +1 -1
  13. package/dist/server/server.d.ts.map +1 -1
  14. package/package.json +8 -8
package/CHANGELOG.md CHANGED
@@ -1,5 +1,27 @@
1
1
  # @mastra/mcp
2
2
 
3
+ ## 1.0.2
4
+
5
+ ### Patch Changes
6
+
7
+ - Fixed MCP tool results returning empty `{}` when the server does not include `structuredContent` in responses (e.g. FastMCP, older MCP protocol versions). The client now extracts the actual result from the `content` array instead of returning the raw protocol envelope, which previously caused output schema validation to strip all properties. ([#13469](https://github.com/mastra-ai/mastra/pull/13469))
8
+
9
+ - Fix MCP client `connect()` creating duplicate connections when called concurrently. This could leak stdio child processes or HTTP sessions. Fixes #13411. ([#13444](https://github.com/mastra-ai/mastra/pull/13444))
10
+
11
+ - Updated dependencies [[`df170fd`](https://github.com/mastra-ai/mastra/commit/df170fd139b55f845bfd2de8488b16435bd3d0da), [`ae55343`](https://github.com/mastra-ai/mastra/commit/ae5534397fc006fd6eef3e4f80c235bcdc9289ef), [`c290cec`](https://github.com/mastra-ai/mastra/commit/c290cec5bf9107225de42942b56b487107aa9dce), [`f03e794`](https://github.com/mastra-ai/mastra/commit/f03e794630f812b56e95aad54f7b1993dc003add), [`aa4a5ae`](https://github.com/mastra-ai/mastra/commit/aa4a5aedb80d8d6837bab8cbb2e301215d1ba3e9), [`de3f584`](https://github.com/mastra-ai/mastra/commit/de3f58408752a8d80a295275c7f23fc306cf7f4f), [`d3fb010`](https://github.com/mastra-ai/mastra/commit/d3fb010c98f575f1c0614452667396e2653815f6), [`702ee1c`](https://github.com/mastra-ai/mastra/commit/702ee1c41be67cc532b4dbe89bcb62143508f6f0), [`f495051`](https://github.com/mastra-ai/mastra/commit/f495051eb6496a720f637fc85b6d69941c12554c), [`e622f1d`](https://github.com/mastra-ai/mastra/commit/e622f1d3ab346a8e6aca6d1fe2eac99bd961e50b), [`861f111`](https://github.com/mastra-ai/mastra/commit/861f11189211b20ddb70d8df81a6b901fc78d11e), [`00f43e8`](https://github.com/mastra-ai/mastra/commit/00f43e8e97a80c82b27d5bd30494f10a715a1df9), [`1b6f651`](https://github.com/mastra-ai/mastra/commit/1b6f65127d4a0d6c38d0a1055cb84527db529d6b), [`96a1702`](https://github.com/mastra-ai/mastra/commit/96a1702ce362c50dda20c8b4a228b4ad1a36a17a), [`cb9f921`](https://github.com/mastra-ai/mastra/commit/cb9f921320913975657abb1404855d8c510f7ac5), [`114e7c1`](https://github.com/mastra-ai/mastra/commit/114e7c146ac682925f0fb37376c1be70e5d6e6e5), [`1b6f651`](https://github.com/mastra-ai/mastra/commit/1b6f65127d4a0d6c38d0a1055cb84527db529d6b), [`72df4a8`](https://github.com/mastra-ai/mastra/commit/72df4a8f9bf1a20cfd3d9006a4fdb597ad56d10a)]:
12
+ - @mastra/core@1.8.0
13
+
14
+ ## 1.0.2-alpha.0
15
+
16
+ ### Patch Changes
17
+
18
+ - Fixed MCP tool results returning empty `{}` when the server does not include `structuredContent` in responses (e.g. FastMCP, older MCP protocol versions). The client now extracts the actual result from the `content` array instead of returning the raw protocol envelope, which previously caused output schema validation to strip all properties. ([#13469](https://github.com/mastra-ai/mastra/pull/13469))
19
+
20
+ - Fix MCP client `connect()` creating duplicate connections when called concurrently. This could leak stdio child processes or HTTP sessions. Fixes #13411. ([#13444](https://github.com/mastra-ai/mastra/pull/13444))
21
+
22
+ - Updated dependencies [[`df170fd`](https://github.com/mastra-ai/mastra/commit/df170fd139b55f845bfd2de8488b16435bd3d0da), [`ae55343`](https://github.com/mastra-ai/mastra/commit/ae5534397fc006fd6eef3e4f80c235bcdc9289ef), [`c290cec`](https://github.com/mastra-ai/mastra/commit/c290cec5bf9107225de42942b56b487107aa9dce), [`f03e794`](https://github.com/mastra-ai/mastra/commit/f03e794630f812b56e95aad54f7b1993dc003add), [`aa4a5ae`](https://github.com/mastra-ai/mastra/commit/aa4a5aedb80d8d6837bab8cbb2e301215d1ba3e9), [`de3f584`](https://github.com/mastra-ai/mastra/commit/de3f58408752a8d80a295275c7f23fc306cf7f4f), [`d3fb010`](https://github.com/mastra-ai/mastra/commit/d3fb010c98f575f1c0614452667396e2653815f6), [`702ee1c`](https://github.com/mastra-ai/mastra/commit/702ee1c41be67cc532b4dbe89bcb62143508f6f0), [`f495051`](https://github.com/mastra-ai/mastra/commit/f495051eb6496a720f637fc85b6d69941c12554c), [`e622f1d`](https://github.com/mastra-ai/mastra/commit/e622f1d3ab346a8e6aca6d1fe2eac99bd961e50b), [`861f111`](https://github.com/mastra-ai/mastra/commit/861f11189211b20ddb70d8df81a6b901fc78d11e), [`00f43e8`](https://github.com/mastra-ai/mastra/commit/00f43e8e97a80c82b27d5bd30494f10a715a1df9), [`1b6f651`](https://github.com/mastra-ai/mastra/commit/1b6f65127d4a0d6c38d0a1055cb84527db529d6b), [`96a1702`](https://github.com/mastra-ai/mastra/commit/96a1702ce362c50dda20c8b4a228b4ad1a36a17a), [`cb9f921`](https://github.com/mastra-ai/mastra/commit/cb9f921320913975657abb1404855d8c510f7ac5), [`114e7c1`](https://github.com/mastra-ai/mastra/commit/114e7c146ac682925f0fb37376c1be70e5d6e6e5), [`1b6f651`](https://github.com/mastra-ai/mastra/commit/1b6f65127d4a0d6c38d0a1055cb84527db529d6b), [`72df4a8`](https://github.com/mastra-ai/mastra/commit/72df4a8f9bf1a20cfd3d9006a4fdb597ad56d10a)]:
23
+ - @mastra/core@1.8.0-alpha.0
24
+
3
25
  ## 1.0.1
4
26
 
5
27
  ### Patch Changes
package/dist/client/client.d.ts.map CHANGED
@@ -1 +1 @@
1
- {"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../src/client/client.ts"],"names":[],"mappings":"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"}
1
+ {"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../src/client/client.ts"],"names":[],"mappings":"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"}
package/dist/docs/SKILL.md CHANGED
@@ -3,7 +3,7 @@ name: mastra-mcp
3
3
  description: Documentation for @mastra/mcp. Use when working with @mastra/mcp APIs, configuration, or implementation.
4
4
  metadata:
5
5
  package: "@mastra/mcp"
6
- version: "1.0.1"
6
+ version: "1.0.2"
7
7
  ---
8
8
 
9
9
  ## When to use
package/dist/docs/assets/SOURCE_MAP.json CHANGED
@@ -1,5 +1,5 @@
1
1
  {
2
- "version": "1.0.1",
2
+ "version": "1.0.2",
3
3
  "package": "@mastra/mcp",
4
4
  "exports": {
5
5
  "UnauthorizedError": {
package/dist/docs/references/docs-mcp-overview.md CHANGED
@@ -9,7 +9,7 @@ Mastra currently supports two MCP classes:
9
9
  1. `MCPClient`: Connects to one or many MCP servers to access their tools, resources, prompts, and handle elicitation requests.
10
10
  2. `MCPServer`: Exposes Mastra tools, agents, workflows, prompts, and resources to MCP-compatible clients.
11
11
 
12
- ## Getting started
12
+ ## Get started
13
13
 
14
14
  To use MCP, install the required dependency:
15
15
 
@@ -42,14 +42,14 @@ bun add @mastra/mcp@latest
42
42
  The `MCPClient` connects Mastra primitives to external MCP servers, which can be local packages (invoked using `npx`) or remote HTTP(S) endpoints. Each server must be configured with either a `command` or a `url`, depending on how it's hosted.
43
43
 
44
44
  ```typescript
45
- import { MCPClient } from "@mastra/mcp";
45
+ import { MCPClient } from '@mastra/mcp'
46
46
 
47
47
  export const testMcpClient = new MCPClient({
48
- id: "test-mcp-client",
48
+ id: 'test-mcp-client',
49
49
  servers: {
50
50
  wikipedia: {
51
- command: "npx",
52
- args: ["-y", "wikipedia-mcp"],
51
+ command: 'npx',
52
+ args: ['-y', 'wikipedia-mcp'],
53
53
  },
54
54
  weather: {
55
55
  url: new URL(
@@ -57,7 +57,7 @@ export const testMcpClient = new MCPClient({
57
57
  ),
58
58
  },
59
59
  },
60
- });
60
+ })
61
61
  ```
62
62
 
63
63
  > **Info:** Visit [MCPClient](https://mastra.ai/reference/tools/mcp-client) for a full list of configuration options.
@@ -69,22 +69,22 @@ export const testMcpClient = new MCPClient({
69
69
  To use tools from an MCP server in an agent, import your `MCPClient` and call `.listTools()` in the `tools` parameter. This loads from the defined MCP servers, making them available to the agent.
70
70
 
71
71
  ```typescript
72
- import { Agent } from "@mastra/core/agent";
73
- import { testMcpClient } from "../mcp/test-mcp-client";
72
+ import { Agent } from '@mastra/core/agent'
73
+ import { testMcpClient } from '../mcp/test-mcp-client'
74
74
 
75
75
  export const testAgent = new Agent({
76
- id: "test-agent",
77
- name: "Test Agent",
78
- description: "You are a helpful AI assistant",
76
+ id: 'test-agent',
77
+ name: 'Test Agent',
78
+ description: 'You are a helpful AI assistant',
79
79
  instructions: `
80
80
  You are a helpful assistant that has access to the following MCP Servers.
81
81
  - Wikipedia MCP Server
82
82
  - US National Weather Service
83
83
 
84
84
  Answer questions using the information you find using the MCP Servers.`,
85
- model: "openai/gpt-5.1",
85
+ model: 'openai/gpt-5.1',
86
86
  tools: await testMcpClient.listTools(),
87
- });
87
+ })
88
88
  ```
89
89
 
90
90
  > **Info:** Visit [Agent Class](https://mastra.ai/reference/agents/agent) for a full list of configuration options.
@@ -94,20 +94,20 @@ export const testAgent = new Agent({
94
94
  To expose agents, tools, and workflows from your Mastra application to external systems over HTTP(S) use the `MCPServer` class. This makes them accessible to any system or agent that supports the protocol.
95
95
 
96
96
  ```typescript
97
- import { MCPServer } from "@mastra/mcp";
97
+ import { MCPServer } from '@mastra/mcp'
98
98
 
99
- import { testAgent } from "../agents/test-agent";
100
- import { testWorkflow } from "../workflows/test-workflow";
101
- import { testTool } from "../tools/test-tool";
99
+ import { testAgent } from '../agents/test-agent'
100
+ import { testWorkflow } from '../workflows/test-workflow'
101
+ import { testTool } from '../tools/test-tool'
102
102
 
103
103
  export const testMcpServer = new MCPServer({
104
- id: "test-mcp-server",
105
- name: "Test Server",
106
- version: "1.0.0",
104
+ id: 'test-mcp-server',
105
+ name: 'Test Server',
106
+ version: '1.0.0',
107
107
  agents: { testAgent },
108
108
  tools: { testTool },
109
109
  workflows: { testWorkflow },
110
- });
110
+ })
111
111
  ```
112
112
 
113
113
  > **Info:** Visit [MCPServer](https://mastra.ai/reference/tools/mcp-server) for a full list of configuration options.
@@ -119,13 +119,13 @@ export const testMcpServer = new MCPServer({
119
119
  To make an MCP server available to other systems or agents that support the protocol, register it in the main `Mastra` instance using `mcpServers`.
120
120
 
121
121
  ```typescript
122
- import { Mastra } from "@mastra/core/mastra";
122
+ import { Mastra } from '@mastra/core/mastra'
123
123
 
124
- import { testMcpServer } from "./mcp/test-mcp-server";
124
+ import { testMcpServer } from './mcp/test-mcp-server'
125
125
 
126
126
  export const mastra = new Mastra({
127
127
  mcpServers: { testMcpServer },
128
- });
128
+ })
129
129
  ```
130
130
 
131
131
  ## Static and dynamic tools
@@ -146,14 +146,14 @@ Use the `.listTools()` method to fetch tools from all configured MCP servers. Th
146
146
  > **Info:** Visit [listTools()](https://mastra.ai/reference/tools/mcp-client) for more information.
147
147
 
148
148
  ```typescript
149
- import { Agent } from "@mastra/core/agent";
149
+ import { Agent } from '@mastra/core/agent'
150
150
 
151
- import { testMcpClient } from "../mcp/test-mcp-client";
151
+ import { testMcpClient } from '../mcp/test-mcp-client'
152
152
 
153
153
  export const testAgent = new Agent({
154
- id: "test-agent",
154
+ id: 'test-agent',
155
155
  tools: await testMcpClient.listTools(),
156
- });
156
+ })
157
157
  ```
158
158
 
159
159
  ### Dynamic tools
@@ -161,14 +161,14 @@ export const testAgent = new Agent({
161
161
  Use the `.listToolsets()` method when tool configuration may vary by request or user, such as in a multi-tenant system where each user provides their own API key. This method returns toolsets that can be passed to the `toolsets` option in the agent's `.generate()` or `.stream()` calls.
162
162
 
163
163
  ```typescript
164
- import { MCPClient } from "@mastra/mcp";
165
- import { mastra } from "./mastra";
164
+ import { MCPClient } from '@mastra/mcp'
165
+ import { mastra } from './mastra'
166
166
 
167
167
  async function handleRequest(userPrompt: string, userApiKey: string) {
168
168
  const userMcp = new MCPClient({
169
169
  servers: {
170
170
  weather: {
171
- url: new URL("http://localhost:8080/mcp"),
171
+ url: new URL('http://localhost:8080/mcp'),
172
172
  requestInit: {
173
173
  headers: {
174
174
  Authorization: `Bearer ${userApiKey}`,
@@ -176,19 +176,19 @@ async function handleRequest(userPrompt: string, userApiKey: string) {
176
176
  },
177
177
  },
178
178
  },
179
- });
179
+ })
180
180
 
181
- const agent = mastra.getAgent("testAgent");
181
+ const agent = mastra.getAgent('testAgent')
182
182
 
183
183
  const response = await agent.generate(userPrompt, {
184
184
  toolsets: await userMcp.listToolsets(),
185
- });
185
+ })
186
186
 
187
- await userMcp.disconnect();
187
+ await userMcp.disconnect()
188
188
 
189
189
  return Response.json({
190
190
  data: response.text,
191
- });
191
+ })
192
192
  }
193
193
  ```
194
194
 
@@ -203,18 +203,20 @@ MCP servers can be discovered through registries. Here's how to connect to some
203
203
  [Klavis AI](https://klavis.ai) provides hosted, enterprise-authenticated, high-quality MCP servers.
204
204
 
205
205
  ```typescript
206
- import { MCPClient } from "@mastra/mcp";
206
+ import { MCPClient } from '@mastra/mcp'
207
207
 
208
208
  const mcp = new MCPClient({
209
209
  servers: {
210
210
  salesforce: {
211
- url: new URL("https://salesforce-mcp-server.klavis.ai/mcp/?instance_id={private-instance-id}"),
211
+ url: new URL(
212
+ 'https://salesforce-mcp-server.klavis.ai/mcp/?instance_id={private-instance-id}',
213
+ ),
212
214
  },
213
215
  hubspot: {
214
- url: new URL("https://hubspot-mcp-server.klavis.ai/mcp/?instance_id={private-instance-id}"),
216
+ url: new URL('https://hubspot-mcp-server.klavis.ai/mcp/?instance_id={private-instance-id}'),
215
217
  },
216
218
  },
217
- });
219
+ })
218
220
  ```
219
221
 
220
222
  Klavis AI offers enterprise-grade authentication and security for production deployments.
@@ -226,15 +228,16 @@ For more details on how to integrate Mastra with Klavis, check out their [docume
226
228
  [mcp.run](https://www.mcp.run/) provides pre-authenticated, managed MCP servers. Tools are grouped into Profiles, each with a unique, signed URL.
227
229
 
228
230
  ```typescript
229
- import { MCPClient } from "@mastra/mcp";
231
+ import { MCPClient } from '@mastra/mcp'
230
232
 
231
233
  const mcp = new MCPClient({
232
234
  servers: {
233
- marketing: { // Example profile name
235
+ marketing: {
236
+ // Example profile name
234
237
  url: new URL(process.env.MCP_RUN_SSE_URL!), // Get URL from mcp.run profile
235
238
  },
236
239
  },
237
- });
240
+ })
238
241
  ```
239
242
 
240
243
  > **Important:** Treat the mcp.run SSE URL like a password. Store it securely, for example, in an environment variable.
@@ -248,18 +251,18 @@ const mcp = new MCPClient({
248
251
  [Composio.dev](https://composio.dev) offers a registry of [SSE-based MCP servers](https://mcp.composio.dev). You can use the SSE URL generated for tools like Cursor directly.
249
252
 
250
253
  ```typescript
251
- import { MCPClient } from "@mastra/mcp";
254
+ import { MCPClient } from '@mastra/mcp'
252
255
 
253
256
  const mcp = new MCPClient({
254
257
  servers: {
255
258
  googleSheets: {
256
- url: new URL("https://mcp.composio.dev/googlesheets/[private-url-path]"),
259
+ url: new URL('https://mcp.composio.dev/googlesheets/[private-url-path]'),
257
260
  },
258
261
  gmail: {
259
- url: new URL("https://mcp.composio.dev/gmail/[private-url-path]"),
262
+ url: new URL('https://mcp.composio.dev/gmail/[private-url-path]'),
260
263
  },
261
264
  },
262
- });
265
+ })
263
266
  ```
264
267
 
265
268
  Authentication with services like Google Sheets often happens interactively through the agent conversation.
@@ -272,44 +275,44 @@ _Note: Composio URLs are typically tied to a single user account, making them be
272
275
 
273
276
  ```typescript
274
277
  // Unix/Mac
275
- import { MCPClient } from "@mastra/mcp";
278
+ import { MCPClient } from '@mastra/mcp'
276
279
 
277
280
  const mcp = new MCPClient({
278
281
  servers: {
279
282
  sequentialThinking: {
280
- command: "npx",
283
+ command: 'npx',
281
284
  args: [
282
- "-y",
283
- "@smithery/cli@latest",
284
- "run",
285
- "@smithery-ai/server-sequential-thinking",
286
- "--config",
287
- "{}",
285
+ '-y',
286
+ '@smithery/cli@latest',
287
+ 'run',
288
+ '@smithery-ai/server-sequential-thinking',
289
+ '--config',
290
+ '{}',
288
291
  ],
289
292
  },
290
293
  },
291
- });
294
+ })
292
295
  ```
293
296
 
294
297
  ```typescript
295
298
  // Windows
296
- import { MCPClient } from "@mastra/mcp";
299
+ import { MCPClient } from '@mastra/mcp'
297
300
 
298
301
  const mcp = new MCPClient({
299
302
  servers: {
300
303
  sequentialThinking: {
301
- command: "npx",
304
+ command: 'npx',
302
305
  args: [
303
- "-y",
304
- "@smithery/cli@latest",
305
- "run",
306
- "@smithery-ai/server-sequential-thinking",
307
- "--config",
308
- "{}",
306
+ '-y',
307
+ '@smithery/cli@latest',
308
+ 'run',
309
+ '@smithery-ai/server-sequential-thinking',
310
+ '--config',
311
+ '{}',
309
312
  ],
310
313
  },
311
314
  },
312
- });
315
+ })
313
316
  ```
314
317
 
315
318
  **Ampersand**:
@@ -320,7 +323,7 @@ const mcp = new MCPClient({
320
323
  // MCPClient with Ampersand MCP Server using SSE
321
324
  export const mcp = new MCPClient({
322
325
  servers: {
323
- "@amp-labs/mcp-server": {
326
+ '@amp-labs/mcp-server': {
324
327
  url: `https://mcp.withampersand.com/v1/sse?${new URLSearchParams({
325
328
  apiKey: process.env.AMPERSAND_API_KEY,
326
329
  project: process.env.AMPERSAND_PROJECT_ID,
@@ -329,28 +332,28 @@ export const mcp = new MCPClient({
329
332
  })}`,
330
333
  },
331
334
  },
332
- });
335
+ })
333
336
  ```
334
337
 
335
338
  ```typescript
336
339
  // If you prefer to run the MCP server locally:
337
- import { MCPClient } from "@mastra/mcp";
340
+ import { MCPClient } from '@mastra/mcp'
338
341
 
339
342
  // MCPClient with Ampersand MCP Server using stdio transport
340
343
  export const mcp = new MCPClient({
341
344
  servers: {
342
- "@amp-labs/mcp-server": {
343
- command: "npx",
345
+ '@amp-labs/mcp-server': {
346
+ command: 'npx',
344
347
  args: [
345
- "-y",
346
- "@amp-labs/mcp-server@latest",
347
- "--transport",
348
- "stdio",
349
- "--project",
348
+ '-y',
349
+ '@amp-labs/mcp-server@latest',
350
+ '--transport',
351
+ 'stdio',
352
+ '--project',
350
353
  process.env.AMPERSAND_PROJECT_ID,
351
- "--integrationName",
354
+ '--integrationName',
352
355
  process.env.AMPERSAND_INTEGRATION_NAME,
353
- "--groupRef",
356
+ '--groupRef',
354
357
  process.env.AMPERSAND_GROUP_REF, // optional
355
358
  ],
356
359
  env: {
@@ -358,7 +361,7 @@ export const mcp = new MCPClient({
358
361
  },
359
362
  },
360
363
  },
361
- });
364
+ })
362
365
  ```
363
366
 
364
367
  As an alternative to MCP, Ampersand's AI SDK also has an adapter for Mastra, so you can [directly import Ampersand tools](https://docs.withampersand.com/ai-sdk#use-with-mastra) for your agent to access.
package/dist/docs/references/docs-mcp-publishing-mcp-server.md CHANGED
@@ -18,19 +18,19 @@ pnpm add @mastra/mcp @mastra/core tsup
18
18
 
19
19
  ```typescript
20
20
  #!/usr/bin/env node
21
- import { MCPServer } from "@mastra/mcp";
22
- import { weatherTool } from "./tools";
21
+ import { MCPServer } from '@mastra/mcp'
22
+ import { weatherTool } from './tools'
23
23
 
24
24
  const server = new MCPServer({
25
- name: "my-mcp-server",
26
- version: "1.0.0",
25
+ name: 'my-mcp-server',
26
+ version: '1.0.0',
27
27
  tools: { weatherTool },
28
- });
28
+ })
29
29
 
30
- server.startStdio().catch((error) => {
31
- console.error("Error running MCP server:", error);
32
- process.exit(1);
33
- });
30
+ server.startStdio().catch(error => {
31
+ console.error('Error running MCP server:', error)
32
+ process.exit(1)
33
+ })
34
34
  ```
35
35
 
36
36
  3. Update your `package.json` to include the `bin` entry pointing to your built server file and a script to build the server with both ESM and CJS outputs.
@@ -75,21 +75,21 @@ To make your MCP server available for others (or yourself) to use via `npx` or a
75
75
  Once published, your MCP server can be used by an `MCPClient` by specifying the command to run your package. You can also use any other MCP client like Claude desktop, Cursor, or Windsurf.
76
76
 
77
77
  ```typescript
78
- import { MCPClient } from "@mastra/mcp";
78
+ import { MCPClient } from '@mastra/mcp'
79
79
 
80
80
  const mcp = new MCPClient({
81
81
  servers: {
82
82
  // Give this MCP server instance a name
83
83
  yourServerName: {
84
- command: "npx",
85
- args: ["-y", "@your-org-name/your-package-name@latest"], // Replace with your package name
84
+ command: 'npx',
85
+ args: ['-y', '@your-org-name/your-package-name@latest'], // Replace with your package name
86
86
  },
87
87
  },
88
- });
88
+ })
89
89
 
90
90
  // You can then get tools or toolsets from this configuration to use in your agent
91
- const tools = await mcp.listTools();
92
- const toolsets = await mcp.listToolsets();
91
+ const tools = await mcp.listTools()
92
+ const toolsets = await mcp.listToolsets()
93
93
  ```
94
94
 
95
95
  Note: If you published without an organization scope, the `args` might just be `["-y", "your-package-name@latest"]`.