@mastra/mcp-docs-server 0.0.0-error-handler-fix-20251020202607 → 0.0.0-execa-dynamic-import-20260304221256

package/.docs/docs/mastra-cloud/deployment.md

@@ -0,0 +1,77 @@
+# Deployment
+
+Deploy your Mastra application to production and expose your agents, tools, and workflows as REST API endpoints.
+
+> **Info:** Mastra Cloud is currently in beta, but many teams are already using it to deploy their agents. It's the easiest way to run Mastra agents in a managed environment.
+
+## Enable deployments
+
+After [setting up your project](https://mastra.ai/docs/mastra-cloud/setup), click **Deployment** in the sidebar and select **Enable Deployments**.
+
+Once enabled, your project automatically builds and deploys. Future pushes to your main branch trigger automatic redeployments.
+
+## Dashboard
+
+The **Overview** page shows your project's domain URL, status, latest deployment, and connected agents and workflows.
+
+![Project dashboard](/assets/images/mastra-cloud-project-dashboard-6890c8032419d5fb075313d08bfd598b.jpg)
+
+Click the **Deployments** menu item to view build logs. Open **Settings** to configure environment variables, branch, storage, and endpoint URLs.
+
+> **Note:** Changes to settings require a new deployment to take effect
+
+## Storage configuration
+
+Mastra Cloud offers two storage options:
+
+1. **Mastra Cloud Store**: Managed storage provided by Mastra Cloud
+2. **Bring your own database**: Connect to your own external database
+
+### Using Mastra Cloud Store
+
+When using the managed Mastra Cloud Store (enabled in your project settings), storage must be configured on the `Mastra` instance, not on individual agent `Memory` instances.
+
+Configure storage on your Mastra instance:
+
+```typescript
+import { Mastra } from '@mastra/core'
+import { LibSQLStore } from '@mastra/libsql'
+
+export const mastra = new Mastra({
+  storage: new LibSQLStore({
+    id: 'mastra-store',
+    url: 'file:./mastra.db',
+  }),
+  agents: { myAgent },
+})
+```
+
+Agents can use Memory without specifying storage as they inherit from the Mastra instance:
+
+```typescript
+import { Agent } from '@mastra/core/agent'
+import { Memory } from '@mastra/memory'
+
+export const myAgent = new Agent({
+  id: 'my-agent',
+  memory: new Memory({
+    // No storage here - uses instance-level storage from Mastra Cloud Store
+    options: {
+      lastMessages: 20,
+    },
+  }),
+})
+```
+
+### Bring your own database
+
+If you don't use Mastra Cloud Store, you can use any [storage provider](https://mastra.ai/docs/memory/storage) with any configuration. Set your database connection strings as environment variables in your project's **Settings** page.
+
+## Using your deployment
+
+After deployment, interact with your agents using the [Mastra Client](https://mastra.ai/docs/server/mastra-client) or call the REST API endpoints directly.
+
+## Next steps
+
+- [Studio](https://mastra.ai/docs/mastra-cloud/studio) - Test your agents in the cloud
+- [Observability](https://mastra.ai/docs/mastra-cloud/observability) - Monitor traces and logs

package/.docs/docs/mastra-cloud/observability.md

@@ -0,0 +1,38 @@
+# Observability
+
+Cloud provides observability for production applications, giving you insight into how your agents and workflows behave. Observability works whether your application is deployed to Mastra Cloud, running locally, or hosted on your own infrastructure. Any Mastra project can send traces and logs to the platform regardless of where it's running.
+
+For details on configuring observability, see the [Cloud Exporter](https://mastra.ai/docs/observability/tracing/exporters/cloud) docs.
+
+## Traces
+
+Traces are available for both agents and workflows by enabling [observability](https://mastra.ai/docs/observability/tracing/overview) using one of the [supported providers](https://mastra.ai/docs/observability/tracing/overview).
+
+### Agents
+
+With observability enabled, you can view detailed outputs from your agents in the **Traces** section in [Studio](https://mastra.ai/docs/mastra-cloud/studio).
+
+![observability agents](/assets/images/mastra-cloud-observability-agents-a51e3bcac8589ba42fc5bd958a627187.jpg)
+
+Agent traces break a run into clear steps: model calls, tool calls, and intermediate chunks. Each includes timing, inputs, outputs, and errors. Drill into any span to inspect prompts, token usage, and results.
+
+### Workflows
+
+With observability enabled, you can view detailed outputs from your workflows in the **Traces** section in [Studio](https://mastra.ai/docs/mastra-cloud/studio).
+
+![observability workflows](/assets/images/mastra-cloud-observability-workflows-47baf49146575e665e3aad9f1fd65e5f.jpg)
+
+Workflow traces capture each step in the run, including transitions, branching, timing, and any tool calls. Inspect inputs, outputs, and errors for every step to debug long-running or multi-step processes.
+
+## Logs
+
+The **Logs** page in the [project dashboard](https://mastra.ai/docs/mastra-cloud/deployment) displays detailed information for debugging and monitoring your application's behavior.
+
+![Dashboard logs](/assets/images/mastra-cloud-dashboard-logs-85576fde4dda03bba2892bb6134a6ebf.jpg)
+
+Each log entry includes its severity level and a detailed message showing agent, workflow, or storage activity.
+
+## Next steps
+
+- [Logging](https://mastra.ai/docs/observability/logging)
+- [Tracing](https://mastra.ai/docs/observability/tracing/overview)

package/.docs/docs/mastra-cloud/overview.md

@@ -0,0 +1,23 @@
+# Mastra Cloud
+
+[Mastra Cloud](https://cloud.mastra.ai) is a platform for deploying, managing, and monitoring Mastra applications. [Import your project](https://mastra.ai/docs/mastra-cloud/setup) to get started.
+
+## Studio
+
+Run [Studio](https://mastra.ai/docs/mastra-cloud/studio) in the cloud and share access with your team via a link. Team members can test agents and workflows, tweak system prompts, and give feedback without running the project locally.
+
+## Deploy
+
+Enable [deployments](https://mastra.ai/docs/mastra-cloud/deployment) and Mastra Cloud hosts your server for you. Connect your GitHub repository for automatic deployments whenever you push to your configured branch. Mastra Cloud exposes your agents, tools, and workflows as REST API endpoints.
+
+Once deployed, the project dashboard gives you visibility into:
+
+- Deployment status and history
+- Build logs and configuration
+- Environment variables and settings
+
+## Observability
+
+[Observability](https://mastra.ai/docs/mastra-cloud/observability) provides insight into how your agents and workflows behave in production. View detailed traces of agent runs, workflow executions, and logs to debug issues and understand performance.
+
+> **Info:** You don’t need to deploy to Mastra Cloud to use Observability. You can send traces to Mastra from any environment

package/.docs/docs/mastra-cloud/setup.md

@@ -0,0 +1,42 @@
+# Setup
+
+Import your Mastra project to [Mastra Cloud](https://cloud.mastra.ai) to use [Studio](https://mastra.ai/docs/mastra-cloud/studio) and optionally [deploy](https://mastra.ai/docs/mastra-cloud/deployment) your agent.
+
+## Before you begin
+
+- [Sign in](https://cloud.mastra.ai) to Cloud
+- Push your [Mastra project](https://mastra.ai/docs/getting-started/start) to GitHub
+
+## Options
+
+![Select project type](/assets/images/mastra-cloud-select-6b31837ad5bcfb2be5f8085a524b576c.png)
+
+When you create a new project, you can choose from three options:
+
+1. **Create from GitHub** - Import a Mastra project from GitHub
+2. **Create from your server** - Connect a self-hosted Mastra instance to [Studio](https://mastra.ai/docs/mastra-cloud/studio)
+3. **Create from template** - Start from a [pre-built template](https://mastra.ai/templates)
+
+To create a project from GitHub, follow these steps:
+
+## Create from GitHub
+
+1. Connect to GitHub when prompted
+
+   ![Deployment details](/assets/images/mastra-cloud-connect-3d62fb8eb348f63097d77079610a6d90.png)
+
+2. Search for your repository and click **Import**
+
+   ![Deployment details](/assets/images/mastra-cloud-import-git-repository-bed773afbf510103f535451cbee5040f.jpg)
+
+3. Configure your project settings. Mastra Cloud auto-detects most settings, but you'll still need to enter the environment variables for your configured [model provider](https://mastra.ai/models):
+
+   ![Deployment details](/assets/images/mastra-cloud-deployment-details-e2c25f0d7d3ede4add9f8a907784c829.jpg)
+
+4. Click **Create Project**
+
+## Next steps
+
+Once your project is imported, [Studio](https://mastra.ai/docs/mastra-cloud/studio) automatically creates a sandbox where you can interact with your agents and share access with your team.
+
+When you're ready for production, enable [Deployment](https://mastra.ai/docs/mastra-cloud/deployment) settings and hit deploy!

package/.docs/docs/mastra-cloud/studio.md

@@ -0,0 +1,24 @@
+# Studio
+
+[YouTube video player](https://www.youtube-nocookie.com/embed/ojGu6Bi4wYk)
+
+Mastra Cloud provides a hosted version of [Studio](https://mastra.ai/docs/getting-started/studio) that gives your team a shared environment for interacting with and testing your agents. Team members can chat with agents, review traces, give feedback, and tweak system prompts - without needing to run the project locally.
+
+[Set up your project](https://mastra.ai/docs/mastra-cloud/setup) to access Studio in the cloud.
+
+See the [Studio documentation](https://mastra.ai/docs/getting-started/studio) for details on features like the Agents playground, Workflows runner, Tools testing, and MCP Servers.
+
+> **Note:** You don't need to deploy your agent to use Studio. Studio runs in a sandbox environment separate from your production deployment
+
+## Sharing access
+
+To invite team members, go to [Mastra Cloud](https://cloud.mastra.ai), click **Team Settings**, then **Members** to add them. Once invited, they can sign in and access your project's Studio.
+
+![Invite team members](/assets/images/mastra-cloud-invite-c91b5a0fff03de5ecba3e0162484c819.png)
+
+> **Warning:** Team members can view environment variables and delete projects. Only invite people you trust.
+
+## Next steps
+
+- [Deployment](https://mastra.ai/docs/mastra-cloud/deployment) - Manage deployments and settings
+- [Observability](https://mastra.ai/docs/mastra-cloud/observability) - Monitor traces and logs

package/.docs/docs/mcp/overview.md

@@ -0,0 +1,373 @@
+# MCP Overview
+
+Mastra supports the [Model Context Protocol (MCP)](https://modelcontextprotocol.io/introduction), an open standard for connecting AI agents to external tools and resources. It serves as a universal plugin system, enabling agents to call tools regardless of language or hosting environment.
+
+Mastra can also be used to author MCP servers, exposing agents, tools, and other structured resources via the MCP interface. These can then be accessed by any system or agent that supports the protocol.
+
+Mastra currently supports two MCP classes:
+
+1. `MCPClient`: Connects to one or many MCP servers to access their tools, resources, prompts, and handle elicitation requests.
+2. `MCPServer`: Exposes Mastra tools, agents, workflows, prompts, and resources to MCP-compatible clients.
+
+## Get started
+
+To use MCP, install the required dependency:
+
+**npm**:
+
+```bash
+npm install @mastra/mcp@latest
+```
+
+**pnpm**:
+
+```bash
+pnpm add @mastra/mcp@latest
+```
+
+**Yarn**:
+
+```bash
+yarn add @mastra/mcp@latest
+```
+
+**Bun**:
+
+```bash
+bun add @mastra/mcp@latest
+```
+
+## Configuring `MCPClient`
+
+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.
+
+```typescript
+import { MCPClient } from '@mastra/mcp'
+
+export const testMcpClient = new MCPClient({
+  id: 'test-mcp-client',
+  servers: {
+    wikipedia: {
+      command: 'npx',
+      args: ['-y', 'wikipedia-mcp'],
+    },
+    weather: {
+      url: new URL(
+        `https://server.smithery.ai/@smithery-ai/national-weather-service/mcp?api_key=${process.env.SMITHERY_API_KEY}`,
+      ),
+    },
+  },
+})
+```
+
+> **Info:** Visit [MCPClient](https://mastra.ai/reference/tools/mcp-client) for a full list of configuration options.
+
+> **Authentication:** For connecting to OAuth-protected MCP servers, see the [OAuth Authentication](https://mastra.ai/reference/tools/mcp-client) section.
+
+## Using `MCPClient` with an agent
+
+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.
+
+```typescript
+import { Agent } from '@mastra/core/agent'
+import { testMcpClient } from '../mcp/test-mcp-client'
+
+export const testAgent = new Agent({
+  id: 'test-agent',
+  name: 'Test Agent',
+  description: 'You are a helpful AI assistant',
+  instructions: `
+      You are a helpful assistant that has access to the following MCP Servers.
+      - Wikipedia MCP Server
+      - US National Weather Service
+
+      Answer questions using the information you find using the MCP Servers.`,
+  model: 'openai/gpt-5.1',
+  tools: await testMcpClient.listTools(),
+})
+```
+
+> **Info:** Visit [Agent Class](https://mastra.ai/reference/agents/agent) for a full list of configuration options.
+
+## Configuring `MCPServer`
+
+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.
+
+```typescript
+import { MCPServer } from '@mastra/mcp'
+
+import { testAgent } from '../agents/test-agent'
+import { testWorkflow } from '../workflows/test-workflow'
+import { testTool } from '../tools/test-tool'
+
+export const testMcpServer = new MCPServer({
+  id: 'test-mcp-server',
+  name: 'Test Server',
+  version: '1.0.0',
+  agents: { testAgent },
+  tools: { testTool },
+  workflows: { testWorkflow },
+})
+```
+
+> **Info:** Visit [MCPServer](https://mastra.ai/reference/tools/mcp-server) for a full list of configuration options.
+
+> **Authentication:** To protect your MCP server with OAuth, see the [OAuth Protection](https://mastra.ai/reference/tools/mcp-server) section.
+
+## Registering an `MCPServer`
+
+To make an MCP server available to other systems or agents that support the protocol, register it in the main `Mastra` instance using `mcpServers`.
+
+```typescript
+import { Mastra } from '@mastra/core/mastra'
+
+import { testMcpServer } from './mcp/test-mcp-server'
+
+export const mastra = new Mastra({
+  mcpServers: { testMcpServer },
+})
+```
+
+## Static and dynamic tools
+
+`MCPClient` offers two approaches to retrieving tools from connected servers, suitable for different application architectures:
+
+| Feature           | Static Configuration (`await mcp.listTools()`) | Dynamic Configuration (`await mcp.listToolsets()`)   |
+| ----------------- | ---------------------------------------------- | ---------------------------------------------------- |
+| **Use Case**      | Single-user, static config (e.g., CLI tool)    | Multi-user, dynamic config (e.g., SaaS app)          |
+| **Configuration** | Fixed at agent initialization                  | Per-request, dynamic                                 |
+| **Credentials**   | Shared across all uses                         | Can vary per user/request                            |
+| **Agent Setup**   | Tools added in `Agent` constructor             | Tools passed in `.generate()` or `.stream()` options |
+
+### Static tools
+
+Use the `.listTools()` method to fetch tools from all configured MCP servers. This is suitable when configuration (such as API keys) is static and consistent across users or requests. Call it once and pass the result to the `tools` property when defining your agent.
+
+> **Info:** Visit [listTools()](https://mastra.ai/reference/tools/mcp-client) for more information.
+
+```typescript
+import { Agent } from '@mastra/core/agent'
+
+import { testMcpClient } from '../mcp/test-mcp-client'
+
+export const testAgent = new Agent({
+  id: 'test-agent',
+  tools: await testMcpClient.listTools(),
+})
+```
+
+### Dynamic tools
+
+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.
+
+```typescript
+import { MCPClient } from '@mastra/mcp'
+import { mastra } from './mastra'
+
+async function handleRequest(userPrompt: string, userApiKey: string) {
+  const userMcp = new MCPClient({
+    servers: {
+      weather: {
+        url: new URL('http://localhost:8080/mcp'),
+        requestInit: {
+          headers: {
+            Authorization: `Bearer ${userApiKey}`,
+          },
+        },
+      },
+    },
+  })
+
+  const agent = mastra.getAgent('testAgent')
+
+  const response = await agent.generate(userPrompt, {
+    toolsets: await userMcp.listToolsets(),
+  })
+
+  await userMcp.disconnect()
+
+  return Response.json({
+    data: response.text,
+  })
+}
+```
+
+> **Info:** Visit [listToolsets()](https://mastra.ai/reference/tools/mcp-client) for more information.
+
+## Connecting to an MCP registry
+
+MCP servers can be discovered through registries. Here's how to connect to some popular ones using `MCPClient`:
+
+**Klavis AI**:
+
+[Klavis AI](https://klavis.ai) provides hosted, enterprise-authenticated, high-quality MCP servers.
+
+```typescript
+import { MCPClient } from '@mastra/mcp'
+
+const mcp = new MCPClient({
+  servers: {
+    salesforce: {
+      url: new URL(
+        'https://salesforce-mcp-server.klavis.ai/mcp/?instance_id={private-instance-id}',
+      ),
+    },
+    hubspot: {
+      url: new URL('https://hubspot-mcp-server.klavis.ai/mcp/?instance_id={private-instance-id}'),
+    },
+  },
+})
+```
+
+Klavis AI offers enterprise-grade authentication and security for production deployments.
+
+For more details on how to integrate Mastra with Klavis, check out their [documentation](https://docs.klavis.ai/documentation/ai-platform-integration/mastra).
+
+**mcp.run**:
+
+[mcp.run](https://www.mcp.run/) provides pre-authenticated, managed MCP servers. Tools are grouped into Profiles, each with a unique, signed URL.
+
+```typescript
+import { MCPClient } from '@mastra/mcp'
+
+const mcp = new MCPClient({
+  servers: {
+    marketing: {
+      // Example profile name
+      url: new URL(process.env.MCP_RUN_SSE_URL!), // Get URL from mcp.run profile
+    },
+  },
+})
+```
+
+> **Important:** Treat the mcp.run SSE URL like a password. Store it securely, for example, in an environment variable.
+>
+> ```bash
+> MCP_RUN_SSE_URL=https://www.mcp.run/api/mcp/sse?nonce=...
+> ```
+
+**Composio.dev**:
+
+[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.
+
+```typescript
+import { MCPClient } from '@mastra/mcp'
+
+const mcp = new MCPClient({
+  servers: {
+    googleSheets: {
+      url: new URL('https://mcp.composio.dev/googlesheets/[private-url-path]'),
+    },
+    gmail: {
+      url: new URL('https://mcp.composio.dev/gmail/[private-url-path]'),
+    },
+  },
+})
+```
+
+Authentication with services like Google Sheets often happens interactively through the agent conversation.
+
+_Note: Composio URLs are typically tied to a single user account, making them best suited for personal automation rather than multi-tenant applications._
+
+**Smithery.ai**:
+
+[Smithery.ai](https://smithery.ai) provides a registry accessible via their CLI.
+
+```typescript
+// Unix/Mac
+import { MCPClient } from '@mastra/mcp'
+
+const mcp = new MCPClient({
+  servers: {
+    sequentialThinking: {
+      command: 'npx',
+      args: [
+        '-y',
+        '@smithery/cli@latest',
+        'run',
+        '@smithery-ai/server-sequential-thinking',
+        '--config',
+        '{}',
+      ],
+    },
+  },
+})
+```
+
+```typescript
+// Windows
+import { MCPClient } from '@mastra/mcp'
+
+const mcp = new MCPClient({
+  servers: {
+    sequentialThinking: {
+      command: 'npx',
+      args: [
+        '-y',
+        '@smithery/cli@latest',
+        'run',
+        '@smithery-ai/server-sequential-thinking',
+        '--config',
+        '{}',
+      ],
+    },
+  },
+})
+```
+
+**Ampersand**:
+
+[Ampersand](https://withampersand.com?utm_source=mastra-docs) offers an [MCP Server](https://docs.withampersand.com/mcp) that allows you to connect your agent to 150+ integrations with SaaS products like Salesforce, Hubspot, and Zendesk.
+
+```typescript
+// MCPClient with Ampersand MCP Server using SSE
+export const mcp = new MCPClient({
+  servers: {
+    '@amp-labs/mcp-server': {
+      url: `https://mcp.withampersand.com/v1/sse?${new URLSearchParams({
+        apiKey: process.env.AMPERSAND_API_KEY,
+        project: process.env.AMPERSAND_PROJECT_ID,
+        integrationName: process.env.AMPERSAND_INTEGRATION_NAME,
+        groupRef: process.env.AMPERSAND_GROUP_REF,
+      })}`,
+    },
+  },
+})
+```
+
+```typescript
+// If you prefer to run the MCP server locally:
+import { MCPClient } from '@mastra/mcp'
+
+// MCPClient with Ampersand MCP Server using stdio transport
+export const mcp = new MCPClient({
+  servers: {
+    '@amp-labs/mcp-server': {
+      command: 'npx',
+      args: [
+        '-y',
+        '@amp-labs/mcp-server@latest',
+        '--transport',
+        'stdio',
+        '--project',
+        process.env.AMPERSAND_PROJECT_ID,
+        '--integrationName',
+        process.env.AMPERSAND_INTEGRATION_NAME,
+        '--groupRef',
+        process.env.AMPERSAND_GROUP_REF, // optional
+      ],
+      env: {
+        AMPERSAND_API_KEY: process.env.AMPERSAND_API_KEY,
+      },
+    },
+  },
+})
+```
+
+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.
+
+## Related
+
+- [Using Tools](https://mastra.ai/docs/agents/using-tools)
+- [MCPClient](https://mastra.ai/reference/tools/mcp-client)
+- [MCPServer](https://mastra.ai/reference/tools/mcp-server)

package/.docs/docs/mcp/publishing-mcp-server.md

@@ -0,0 +1,95 @@
+# Publishing an MCP Server
+
+This example guides you through setting up a basic Mastra MCPServer using the stdio transport, building it, and preparing it for publishing to NPM.
+
+## Install dependencies
+
+Install the necessary packages:
+
+```bash
+pnpm add @mastra/mcp @mastra/core tsup
+```
+
+## Setting up an MCP Server
+
+1. Create a file for your stdio server, for example, `/src/mastra/stdio.ts`.
+
+2. Add the following code to the file. Remember to import your actual Mastra tools and name the server appropriately.
+
+   ```typescript
+   #!/usr/bin/env node
+   import { MCPServer } from '@mastra/mcp'
+   import { weatherTool } from './tools'
+
+   const server = new MCPServer({
+     name: 'my-mcp-server',
+     version: '1.0.0',
+     tools: { weatherTool },
+   })
+
+   server.startStdio().catch(error => {
+     console.error('Error running MCP server:', error)
+     process.exit(1)
+   })
+   ```
+
+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.
+
+   ```json
+   {
+     "bin": "dist/stdio.mjs",
+     "scripts": {
+       "build:mcp": "tsup src/mastra/stdio.ts --format esm,cjs --no-splitting --dts && echo '#!/usr/bin/env node' | cat - dist/stdio.mjs > temp && mv temp dist/stdio.mjs && chmod +x dist/stdio.mjs"
+     }
+   }
+   ```
+
+   The build command generates both ESM (`.mjs`) and CJS (`.cjs`) outputs for maximum compatibility. The shebang (`#!/usr/bin/env node`) is prepended to the ESM artifact to make it directly executable, and the `bin` entry points to this file.
+
+4. Run the build command:
+
+   ```bash
+   pnpm run build:mcp
+   ```
+
+   This will compile your server code into both ESM and CJS formats and make the ESM output file executable. On Unix-like systems, the `chmod +x` step makes the file directly executable. Windows users may need to use WSL or handle execution through Node.js directly.
+
+## Publishing to NPM
+
+To make your MCP server available for others (or yourself) to use via `npx` or as a dependency, you can publish it to NPM.
+
+1. Ensure you have an NPM account and are logged in (`npm login`).
+
+2. Make sure your package name in `package.json` is unique and available.
+
+3. Run the publish command from your project root after building:
+
+   ```bash
+   npm publish --access public
+   ```
+
+   For more details on publishing packages, refer to the [NPM documentation](https://docs.npmjs.com/creating-and-publishing-scoped-public-packages).
+
+## Using a published MCP Server
+
+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.
+
+```typescript
+import { MCPClient } from '@mastra/mcp'
+
+const mcp = new MCPClient({
+  servers: {
+    // Give this MCP server instance a name
+    yourServerName: {
+      command: 'npx',
+      args: ['-y', '@your-org-name/your-package-name@latest'], // Replace with your package name
+    },
+  },
+})
+
+// You can then get tools or toolsets from this configuration to use in your agent
+const tools = await mcp.listTools()
+const toolsets = await mcp.listToolsets()
+```
+
+Note: If you published without an organization scope, the `args` might just be `["-y", "your-package-name@latest"]`.