@mastra/mcp 1.17.0-alpha.0 → 1.17.0-alpha.1

package/CHANGELOG.md

@@ -1,5 +1,37 @@
 # @mastra/mcp
 
+## 1.17.0-alpha.1
+
+### Minor Changes
+
+- MCP tools served over HTTP now see the authenticated caller. When an MCP server runs behind a Mastra server with `server.auth` configured, the resolved user is bridged into `extra.authInfo` automatically, on both the streamable HTTP and SSE transports. Previously `extra.authInfo` was always undefined because the request handed to the MCP transport was rebuilt without the auth data. ([#21689](https://github.com/mastra-ai/mastra/pull/21689))
+
+  **Custom verification**
+
+  If your own middleware verifies the caller, build the auth info yourself with the new `server.mcpOptions.setRequestAuth` hook:
+
+  ```ts
+  export const mastra = new Mastra({
+    mcpServers: { myServer },
+    server: {
+      middleware: [verifyBearerToken],
+      mcpOptions: {
+        setRequestAuth: (req, requestContext) => {
+          const payload = requestContext.get('bearerPayload');
+          req.auth = { token: payload.token, clientId: payload.sub, scopes: payload.scope.split(' ') };
+        },
+      },
+    },
+  });
+  ```
+
+  Fixes #17291
+
+### Patch Changes
+
+- Updated dependencies [[`4e7a421`](https://github.com/mastra-ai/mastra/commit/4e7a421dce8a48742f785d1e93ad2f43a572b282), [`242e324`](https://github.com/mastra-ai/mastra/commit/242e3241e73cbd5c9bb86a31ebb49ca0256488d4), [`217e967`](https://github.com/mastra-ai/mastra/commit/217e9672d8b3160eb729d8e9f0044949e88da239), [`d774e89`](https://github.com/mastra-ai/mastra/commit/d774e8930c781df8c9effe3763e6b501c099b6cc), [`9c27a53`](https://github.com/mastra-ai/mastra/commit/9c27a53cd9d3de4f3f025bc387d94ce371c33f95), [`dff25a1`](https://github.com/mastra-ai/mastra/commit/dff25a1103fa72ee082a9b6f805ebeb5ce400753), [`217e967`](https://github.com/mastra-ai/mastra/commit/217e9672d8b3160eb729d8e9f0044949e88da239), [`7f78585`](https://github.com/mastra-ai/mastra/commit/7f785857e401570e2ffb316911f126ed363aa537), [`f2a4afd`](https://github.com/mastra-ai/mastra/commit/f2a4afd7e37e809669001ed17724b341a5c1f45e), [`d438148`](https://github.com/mastra-ai/mastra/commit/d438148e222c1e2fb3c652725ce75680962ebec4), [`ba05fe0`](https://github.com/mastra-ai/mastra/commit/ba05fe0738f70cb686777546e968237d09269142), [`d26a8d4`](https://github.com/mastra-ai/mastra/commit/d26a8d4281f28414715b333c85bedaf70d0b2890), [`677cdc6`](https://github.com/mastra-ai/mastra/commit/677cdc6af564dec29a13464d12b7ab2a4efc22e9), [`a318490`](https://github.com/mastra-ai/mastra/commit/a318490e17da32f338d50929c770d901a9b3dd72), [`763e0c6`](https://github.com/mastra-ai/mastra/commit/763e0c61e04d76ad9a9efd301aa57525ca0cbea9), [`23e0be2`](https://github.com/mastra-ai/mastra/commit/23e0be261381e49534b4ff3101c60ee64a946cbf), [`7fc8806`](https://github.com/mastra-ai/mastra/commit/7fc880627d3cbf995d31ea0e8b807bf15417e651), [`0e02eac`](https://github.com/mastra-ai/mastra/commit/0e02eacdb2e30e1697a41910b41163742a181dc1), [`4df174c`](https://github.com/mastra-ai/mastra/commit/4df174c32bddf093a82f273070b8380aef7c9e90), [`f7c25b5`](https://github.com/mastra-ai/mastra/commit/f7c25b5106ddfb48e591f98df7a51e0f2dd01dba), [`dc09cc1`](https://github.com/mastra-ai/mastra/commit/dc09cc1083d861cde192c1cd235324dc75b8c731), [`36b4649`](https://github.com/mastra-ai/mastra/commit/36b4649045a3a380cbab8ceca866db4086223aff), [`377eb81`](https://github.com/mastra-ai/mastra/commit/377eb81ce43b964e3a6b541df172da74a8ff3716)]:
+  - @mastra/core@1.60.0-alpha.8
+
 ## 1.17.0-alpha.0
 
 ### Minor Changes

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: "1.17.0-alpha.0"
+  version: "1.17.0-alpha.1"
 ---
 
 ## When to use
@@ -16,9 +16,9 @@ Read the individual reference documents for detailed explanations and code examp
 
 ### Docs
 
+- [Fine-Grained Authorization (FGA)](references/docs-auth-fga.md) - Add resource-level authorization to your Mastra application with FGA providers.
+- [MCP](references/docs-connections-mcp.md) - Connect Mastra agents to external MCP servers and expose Mastra tools through MCPServer. You can also build interactive MCP Apps for Studio.
 - [Connections](references/docs-connections-overview.md) - Connect Mastra to remote agents, coding agents, provider software development kit runtimes, and external tools and resources.
-- [MCP](references/docs-mcp-overview.md) - Connect Mastra agents to external MCP servers and expose Mastra tools through MCPServer. You can also build interactive MCP Apps for Studio.
-- [Fine-Grained Authorization (FGA)](references/docs-server-auth-fga.md) - Add resource-level authorization to your Mastra application with FGA providers.
 
 ### Reference
 

package/dist/docs/assets/SOURCE_MAP.json

@@ -1,5 +1,5 @@
 {
-  "version": "1.17.0-alpha.0",
+  "version": "1.17.0-alpha.1",
   "package": "@mastra/mcp",
   "exports": {},
   "modules": {}

package/dist/docs/references/{docs-server-auth-fga.md → docs-auth-fga.md}

@@ -299,5 +299,5 @@ The actor signal is trusted input, so construct it server-side:
 ## Related
 
 - [`IFGAProvider` reference](https://mastra.ai/reference/auth/fga)
-- [Authentication overview](https://mastra.ai/docs/server/auth)
+- [Authentication overview](https://mastra.ai/docs/auth/overview)
 - [WorkOS authentication](https://mastra.ai/integrations/auth/workos)

package/dist/docs/references/{docs-mcp-overview.md → docs-connections-mcp.md}

@@ -406,7 +406,7 @@ App iframes allow scripts, forms, and popups. They can't access the parent page'
 
 ## Next steps
 
-- [Use tools with agents](https://mastra.ai/docs/agents/using-tools)
+- [Use tools with agents](https://mastra.ai/docs/agents/tools)
 - [`MCPClient` reference](https://mastra.ai/reference/tools/mcp-client)
 - [`MCPServer` reference](https://mastra.ai/reference/tools/mcp-server)
 - [MCP Apps extension specification](https://github.com/modelcontextprotocol/ext-apps)

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

@@ -4,10 +4,10 @@
 
 Connections let Mastra work with remote agents, coding agents, provider software development kit (SDK) runtimes, and external tools and resources. Choose a connection type based on which system owns the agent runtime and what you need to exchange.
 
-- [**Agent-to-Agent (A2A)**](https://mastra.ai/docs/agents/a2a): Expose or consume remote agents across service, framework, vendor, and language boundaries.
-- [**Agent Client Protocol (ACP)**](https://mastra.ai/docs/agents/acp): Run compatible coding-agent processes as Mastra tools or subagents.
-- [**SDK agents**](https://mastra.ai/docs/agents/sdk-agents): Register Claude, Cursor, or OpenAI SDK-backed agents while the provider SDK retains control of the runtime, tools, permissions, and agent loop.
-- [**Model Context Protocol (MCP)**](https://mastra.ai/docs/mcp/overview): Connect agents to external tools and resources, or expose Mastra agents, tools, workflows, prompts, and resources to MCP-compatible systems.
+- [**Model Context Protocol (MCP)**](https://mastra.ai/docs/connections/mcp): Connect agents to external tools and resources, or expose Mastra agents, tools, workflows, prompts, and resources to MCP-compatible systems.
+- [**Agent-to-Agent (A2A)**](https://mastra.ai/docs/connections/a2a): Expose or consume remote agents across service, framework, vendor, and language boundaries.
+- [**Agent Client Protocol (ACP)**](https://mastra.ai/docs/connections/acp): Run compatible coding-agent processes as Mastra tools or subagents.
+- [**SDK agents**](https://mastra.ai/docs/connections/sdk-agents): Register Claude, Cursor, or OpenAI SDK-backed agents while the provider SDK retains control of the runtime, tools, permissions, and agent loop.
 
 ## When to use connections
 
@@ -20,7 +20,7 @@ Use connections when you need to:
 
 ## Get started
 
-Start with the boundary you need to cross. Use [A2A](https://mastra.ai/docs/agents/a2a) for remote agent endpoints, [ACP](https://mastra.ai/docs/agents/acp) for coding-agent processes, [SDK agents](https://mastra.ai/docs/agents/sdk-agents) for provider-owned runtimes, or [MCP](https://mastra.ai/docs/mcp/overview) for tools and resources.
+Start with the boundary you need to cross. Use [A2A](https://mastra.ai/docs/connections/a2a) for remote agent endpoints, [ACP](https://mastra.ai/docs/connections/acp) for coding-agent processes, [SDK agents](https://mastra.ai/docs/connections/sdk-agents) for provider-owned runtimes, or [MCP](https://mastra.ai/docs/connections/mcp) for tools and resources.
 
 **A2A**:
 

package/dist/docs/references/reference-editor-tools.md

@@ -4,7 +4,7 @@
 
 Editor stores tool selections as part of an agent version. A stored configuration can add registered tools and tools from integration providers, as well as tools from Model Context Protocol (MCP) clients.
 
-See [Editor tools](https://mastra.ai/docs/editor/overview) for the Studio workflow and common uses.
+See [Editor tools](https://mastra.ai/docs/studio/editor) for the Studio workflow and common uses.
 
 ## Tool sources
 

package/dist/docs/references/reference-tools-mcp-server.md

@@ -168,6 +168,51 @@ const fetchUserData = createTool({
 })
 ```
 
+#### Where `authInfo` comes from
+
+When an MCP server is served by a Mastra server, `extra.authInfo` is populated from the principal resolved by `server.auth`. Nothing extra is required:
+
+```typescript
+export const mastra = new Mastra({
+  mcpServers: { myServer },
+  server: {
+    auth: new MastraJwtAuth({ secret: process.env.JWT_SECRET! }),
+  },
+})
+```
+
+The authenticated user is mapped to `authInfo` as:
+
+| `authInfo` field | Value                                                                      |
+| ---------------- | -------------------------------------------------------------------------- |
+| `token`          | The bearer token or session cookie value used for the request              |
+| `clientId`       | The first present of `user.id`, `user.sub`, `user.userId`, `user.email`    |
+| `scopes`         | `user.scopes`, `user.scope`, or `user.permissions`, normalized to an array |
+| `extra.user`     | The full user object returned by the auth provider                         |
+
+If your own middleware performs the verification, set `server.mcpOptions.setRequestAuth` to build `authInfo` yourself. The hook replaces the default mapping and applies to both the streamable HTTP and SSE transports:
+
+```typescript
+export const mastra = new Mastra({
+  mcpServers: { myServer },
+  server: {
+    middleware: [verifyBearerToken], // stores the payload on the request context
+    mcpOptions: {
+      setRequestAuth: (req, requestContext) => {
+        const payload = requestContext.get('bearerPayload')
+        req.auth = {
+          token: payload.token,
+          clientId: payload.sub,
+          scopes: payload.scope.split(' '),
+        }
+      },
+    },
+  },
+})
+```
+
+Leaving `req.auth` unset inside the hook opts the request out of auth info entirely.
+
 ## Methods
 
 These are the functions you can call on an `MCPServer` instance to control its behavior and get information.
@@ -929,7 +974,7 @@ Notification methods (`resources.notifyListChanged()`, `prompts.notifyListChange
 
 ## Examples
 
-For a practical example of packaging a stdio server, see [Publish a stdio server package](https://mastra.ai/docs/mcp/overview).
+For a practical example of packaging a stdio server, see [Publish a stdio server package](https://mastra.ai/docs/connections/mcp).
 
 The example at the beginning of this page also demonstrates how to instantiate `MCPServer` with both tools and agents.
 
@@ -1663,7 +1708,7 @@ const server = new MCPServer({
 })
 ```
 
-Link a tool to its app resource by setting `mcp._meta.ui.resourceUri` in `createTool()` to the matching `ui://` URI. The server normalizes this metadata for older hosts when listing tools. Visit [MCP Apps](https://mastra.ai/docs/mcp/overview) for the full app bridge API and usage patterns.
+Link a tool to its app resource by setting `mcp._meta.ui.resourceUri` in `createTool()` to the matching `ui://` URI. The server normalizes this metadata for older hosts when listing tools. Visit [MCP Apps](https://mastra.ai/docs/connections/mcp) for the full app bridge API and usage patterns.
 
 ## Related information
 

package/dist/index.cjs

@@ -26555,6 +26555,8 @@ var MCPServer = class extends _mastra_core_mcp.MCPServerBase {
 	stdioTransport;
 	sseTransport;
 	sseHonoTransports;
+	/** Auth info for the in-flight Hono SSE message POST, keyed by session id. */
+	sseHonoAuthInfo = /* @__PURE__ */ new Map();
 	streamableHTTPTransports = /* @__PURE__ */ new Map();
 	httpServerInstances = /* @__PURE__ */ new Map();
 	resourceOptions;
@@ -27731,7 +27733,7 @@ var MCPServer = class extends _mastra_core_mcp.MCPServerBase {
 	* export default app;
 	* ```
 	*/
-	async startHonoSSE({ url, ssePath, messagePath, context }) {
+	async startHonoSSE({ url, ssePath, messagePath, context, authInfo }) {
 		const honoContext = context;
 		try {
 			if (url.pathname === ssePath) return streamSSE(honoContext, async (stream) => {
@@ -27746,6 +27748,8 @@ var MCPServer = class extends _mastra_core_mcp.MCPServerBase {
 				this.logger.debug("Received message for sessionId", { sessionId });
 				if (!sessionId) return honoContext.text("No sessionId provided", 400);
 				if (!this.sseHonoTransports.has(sessionId)) return honoContext.text(`No transport found for sessionId ${sessionId}`, 400);
+				if (authInfo) this.sseHonoAuthInfo.set(sessionId, authInfo);
+				else this.sseHonoAuthInfo.delete(sessionId);
 				const message = await this.sseHonoTransports.get(sessionId)?.handlePostMessage(honoContext);
 				if (!message) return honoContext.text("Transport not found", 400);
 				return message;
@@ -28098,12 +28102,22 @@ var MCPServer = class extends _mastra_core_mcp.MCPServerBase {
 		stream.onAbort(() => {
 			this.logger.debug("SSE Transport aborted with sessionId:", { sessionId });
 			this.sseHonoTransports.delete(sessionId);
+			this.sseHonoAuthInfo.delete(sessionId);
 		});
 		try {
 			await this.server.connect(sseTransport);
+			const onmessage = sseTransport.onmessage?.bind(sseTransport);
+			if (onmessage) sseTransport.onmessage = (message, extra) => {
+				const authInfo = this.sseHonoAuthInfo.get(sessionId);
+				onmessage(message, authInfo ? {
+					...extra,
+					authInfo
+				} : extra);
+			};
 			this.server.onclose = async () => {
 				this.logger.debug("SSE Transport closed with sessionId:", { sessionId });
 				this.sseHonoTransports.delete(sessionId);
+				this.sseHonoAuthInfo.delete(sessionId);
 				await this.server.close();
 			};
 			while (true) {