@mastra/mcp 2.9.0-alpha.3 → 2.9.0-alpha.5

package/dist/docs/SKILL.md

@@ -3,7 +3,7 @@ name: mastra-mcp
 description: Documentation for @mastra/mcp. Use when working with @mastra/mcp APIs, configuration, or implementation.
 metadata:
   package: "@mastra/mcp"
-  version: "2.9.0-alpha.3"
+  version: "2.9.0-alpha.5"
 ---
 
 ## When to use
@@ -19,6 +19,7 @@ Read the individual reference documents for detailed explanations and code examp
 - [Fine-Grained Authorization (FGA)](references/docs-auth-fga.md) - Configure Mastra Fine-Grained Authorization for resource-level permissions that map routes to actions and scope stored resources for enterprise users.
 - [MCP](references/docs-connections-mcp.md) - Connect Mastra agents to remote MCP servers, expose Mastra tools through MCPServer, manage approvals, subscribe to MCP events, and build interactive MCP Apps for Studio.
 - [MCP authentication and authorization](references/docs-guides-mcp-authentication-authorization.md) - Choose credentials for MCP connections, protect a Mastra MCP server, and separate delegated access from tool and data permissions.
+- [Built-in MCP server](references/docs-server-mcp.md) - Let MCP clients such as Claude Code, Cursor, and the MCP Inspector call your agents, workflows, and tools through the built-in /api/mcp endpoint, with the same auth, RBAC, and FGA as the HTTP API.
 
 ### Reference
 

package/dist/docs/assets/SOURCE_MAP.json

@@ -1,71 +1,71 @@
 {
-  "version": "2.9.0-alpha.3",
+  "version": "2.9.0-alpha.5",
   "package": "@mastra/mcp",
   "exports": {
     "InMemoryMCPEventCursorStore": {
       "types": "dist/integrations/events-cursor-store.d.ts",
       "implementation": "dist/index.js",
-      "line": 25452
+      "line": 25752
     },
     "InMemoryMCPTaskStore": {
       "types": "dist/server/tasks/in-memory-store.d.ts",
       "implementation": "dist/index.js",
-      "line": 22227
+      "line": 22527
     },
     "InMemoryOAuthStorage": {
       "types": "dist/client/oauth-provider.d.ts",
       "implementation": "dist/index.js",
-      "line": 17800
+      "line": 18100
     },
     "InMemoryWebhookSubscriptionStore": {
       "types": "dist/server/events/webhook-store.d.ts",
       "implementation": "dist/index.js",
-      "line": 20597
+      "line": 20897
     },
     "InternalMastraMCPClient": {
       "types": "dist/client/client.d.ts",
       "implementation": "dist/index.js",
-      "line": 16070
+      "line": 16370
     },
     "MCPClient": {
       "types": "dist/client/configuration.d.ts",
       "implementation": "dist/index.js",
-      "line": 18293
+      "line": 18593
     },
     "MCPClientServerProxy": {
       "types": "dist/client/server-proxy.d.ts",
       "implementation": "dist/index.js",
-      "line": 18141
+      "line": 18441
     },
     "MCPEventsSignalProvider": {
       "types": "dist/integrations/events-signals.d.ts",
       "implementation": "dist/index.js",
-      "line": 25637
+      "line": 25937
     },
     "MCPOAuthClientProvider": {
       "types": "dist/client/oauth-provider.d.ts",
       "implementation": "dist/index.js",
-      "line": 17852
+      "line": 18152
     },
     "MCPServer": {
       "types": "dist/server/server.d.ts",
       "implementation": "dist/index.js",
-      "line": 23242
+      "line": 23542
     },
     "MCPTaskLimitError": {
       "types": "dist/server/tasks/store.d.ts",
       "implementation": "dist/index.js",
-      "line": 21409
+      "line": 21709
     },
     "MCP_CALL_TOOL_CONTENT": {
       "types": "dist/client/client.d.ts",
       "implementation": "dist/index.js",
-      "line": 15914
+      "line": 16214
     },
     "MCP_CALL_TOOL_META": {
       "types": "dist/client/client.d.ts",
       "implementation": "dist/index.js",
-      "line": 15916
+      "line": 16216
     },
     "MCP_CLIENT_PROTOCOL_VERSION": {
       "types": "dist/client/types.d.ts",
@@ -75,122 +75,122 @@
     "MCP_DISCOVERY_TIMEOUT_CODE": {
       "types": "dist/client/configuration.d.ts",
       "implementation": "dist/index.js",
-      "line": 18262
+      "line": 18562
     },
     "MCP_PROTOCOL_VERSION": {
       "types": "dist/server/types.d.ts",
       "implementation": "dist/index.js",
-      "line": 25179
+      "line": 25479
     },
     "ServerEventActions": {
       "types": "dist/server/events/actions.d.ts",
       "implementation": "dist/index.js",
-      "line": 19698
+      "line": 19998
     },
     "ServerPromptActions": {
       "types": "dist/server/actions.d.ts",
       "implementation": "dist/index.js",
-      "line": 19678
+      "line": 19978
     },
     "ServerResourceActions": {
       "types": "dist/server/actions.d.ts",
       "implementation": "dist/index.js",
-      "line": 19664
+      "line": 19964
     },
     "ServerToolActions": {
       "types": "dist/server/actions.d.ts",
       "implementation": "dist/index.js",
-      "line": 19646
+      "line": 19946
     },
     "createIntrospectionValidator": {
       "types": "dist/server/oauth-middleware.d.ts",
       "implementation": "dist/index.js",
-      "line": 25371
+      "line": 25671
     },
     "createOAuthCallbackServer": {
       "types": "dist/client/oauth-callback-server.d.ts",
       "implementation": "dist/index.js",
-      "line": 17682
+      "line": 17982
     },
     "createOAuthMiddleware": {
       "types": "dist/server/oauth-middleware.d.ts",
       "implementation": "dist/index.js",
-      "line": 25224
+      "line": 25524
     },
     "createSimpleTokenProvider": {
       "types": "dist/client/oauth-provider.d.ts",
       "implementation": "dist/index.js",
-      "line": 18115
+      "line": 18415
     },
     "createStaticTokenValidator": {
       "types": "dist/server/oauth-middleware.d.ts",
       "implementation": "dist/index.js",
-      "line": 25340
+      "line": 25640
     },
     "defineEvent": {
       "types": "dist/server/events/define-event.d.ts",
       "implementation": "dist/index.js",
-      "line": 25442
+      "line": 25742
     },
     "extractBearerToken": {
       "types": "dist/shared/oauth-types.d.ts",
       "implementation": "dist/index.js",
-      "line": 13220
+      "line": 13520
     },
     "generateProtectedResourceMetadata": {
       "types": "dist/shared/oauth-types.d.ts",
       "implementation": "dist/index.js",
-      "line": 13204
+      "line": 13504
     },
     "generateWWWAuthenticateHeader": {
       "types": "dist/shared/oauth-types.d.ts",
       "implementation": "dist/index.js",
-      "line": 13189
+      "line": 13489
     },
     "getCallbackUrlCandidates": {
       "types": "dist/client/oauth-callback-server.d.ts",
       "implementation": "dist/index.js",
-      "line": 17615
+      "line": 17915
     },
     "getMcpCallToolContent": {
       "types": "dist/client/client.d.ts",
       "implementation": "dist/index.js",
-      "line": 15936
+      "line": 16236
     },
     "getMcpCallToolMeta": {
       "types": "dist/client/client.d.ts",
       "implementation": "dist/index.js",
-      "line": 15945
+      "line": 16245
     },
     "isMCPTaskStoreAdmin": {
       "types": "dist/server/tasks/store.d.ts",
       "implementation": "dist/index.js",
-      "line": 21460
+      "line": 21760
     },
     "isWorkflowTaskContext": {
       "types": "dist/server/tasks/workflow-runs.d.ts",
       "implementation": "dist/index.js",
-      "line": 23000
+      "line": 23300
     },
     "principalKeyOf": {
       "types": "dist/server/tasks/store.d.ts",
       "implementation": "dist/index.js",
-      "line": 21401
+      "line": 21701
     },
     "taskKeyOf": {
       "types": "dist/shared/tasks/task-id.d.ts",
       "implementation": "dist/index.js",
-      "line": 13384
+      "line": 13684
     },
     "traceContextFromMeta": {
       "types": "dist/shared/trace-context.d.ts",
       "implementation": "dist/index.js",
-      "line": 13406
+      "line": 13706
     },
     "traceContextToMeta": {
       "types": "dist/shared/trace-context.d.ts",
       "implementation": "dist/index.js",
-      "line": 13418
+      "line": 13718
     }
   },
   "modules": {}

package/dist/docs/references/docs-connections-mcp.md

@@ -200,6 +200,8 @@ export async function handleRequest(prompt: string, apiKey: string) {
 
 Visit [`listTools()`](https://mastra.ai/reference/tools/mcp-client) and [`listToolsets()`](https://mastra.ai/reference/tools/mcp-client) for their full APIs.
 
+This example finishes within one request. When agent work must continue after the request ends or survive a process restart, use [durable agents](https://mastra.ai/docs/harness/durable-agents) or [background tasks](https://mastra.ai/docs/harness/background-tasks) instead of building your own task tracking. Call-time `toolsets` can't move to another process, so with a durable agent, load per-request MCP tools in the agent's `tools` function from [request context](https://mastra.ai/docs/server/request-context).
+
 ### Tool approval
 
 Set `requireToolApproval` on a server to require approval for all its tools:
@@ -287,6 +289,8 @@ A tool that needs something from the user before it can finish calls `context.su
 
 Visit the [`MCPServer` reference](https://mastra.ai/reference/tools/mcp-server) for prompts, resources, transports, and other server options.
 
+To expose every agent, workflow, and tool on your Mastra app without defining a server, use the [built-in MCP server](https://mastra.ai/docs/server/mcp) at `/api/mcp`.
+
 ### Publish a stdio server package
 
 Package a server that uses the standard input/output (stdio) transport when you want clients to run it locally through a command such as `npx`. Create a separate executable entry point that starts the server:
@@ -444,71 +448,6 @@ export const mastra = new Mastra({
 
 Tools loaded through `listTools()` include a `serverId` in `_meta.ui`, allowing Studio to resolve each app resource without scanning every server. Visit [`toMCPServerProxies()`](https://mastra.ai/reference/tools/mcp-client) for proxy configuration details.
 
-### Use prebuilt Mastra apps
-
-The `@mastra/mcp-apps-components` package includes prebuilt MCP Apps. Each one is a self-contained HTML page that you register as an app resource, next to the tools it talks to.
-
-**npm**:
-
-```bash
-npm install @mastra/mcp-apps-components
-```
-
-**pnpm**:
-
-```bash
-pnpm add @mastra/mcp-apps-components
-```
-
-**Yarn**:
-
-```bash
-yarn add @mastra/mcp-apps-components
-```
-
-**Bun**:
-
-```bash
-bun add @mastra/mcp-apps-components
-```
-
-`greetingApp` greets someone by name. The host sends it the arguments of the tool that opened it, and the app reads `name`. It then calls the `getGreeting` tool on the same server for its data and shows the `greeting` from the result. Mark `getGreeting` as app-only with `visibility: ['app']`, so the model doesn't see it:
-
-```typescript
-import { createTool } from '@mastra/core/tools'
-import { MCPServer } from '@mastra/mcp'
-import { greetingApp } from '@mastra/mcp-apps-components'
-import { z } from 'zod'
-
-const uri = 'ui://mastra/greeting'
-
-export const greetingServer = new MCPServer({
-  id: 'greeting-server',
-  name: 'Greeting Server',
-  version: '1.0.0',
-  appResources: { [uri]: greetingApp },
-  tools: {
-    showGreeting: createTool({
-      id: 'showGreeting',
-      description: 'Shows a greeting card for someone',
-      inputSchema: z.object({ name: z.string() }),
-      mcp: { _meta: { ui: { resourceUri: uri } } },
-      execute: async ({ name }) => ({ name }),
-    }),
-    getGreeting: createTool({
-      id: 'getGreeting',
-      description: 'Returns the greeting for a name',
-      inputSchema: z.object({ name: z.string() }),
-      outputSchema: z.object({ greeting: z.string() }),
-      mcp: { _meta: { ui: { resourceUri: uri, visibility: ['app'] } } },
-      execute: async ({ name }) => ({ greeting: `Hello, ${name}!` }),
-    }),
-  },
-})
-```
-
-`getGreeting` runs on your server, so it can call any API with your server's credentials. The app's iframe has no network access of its own.
-
 ### Sandbox security
 
 Mastra Studio uses [`@mcp-ui/client`](https://www.npmjs.com/package/@mcp-ui/client) to load app HTML through a sandbox proxy and communicate over JSON-RPC with `postMessage`.