@mastra/mcp-docs-server 1.3.8-alpha.5 → 1.3.8-alpha.7

package/.docs/docs/guides/mcp-authentication-authorization.md

@@ -93,6 +93,14 @@ Configure validation appropriate to your issuer, including audience and expiry c
 
 Protecting Mastra routes with `server.auth` and providing interoperable OAuth discovery are different tasks. Don't assume configuring one supplies the other.
 
+### Routes Mastra registers for an MCP server
+
+Alongside the MCP transport, Mastra registers REST routes used by Studio to list servers, inspect tools, execute tools, and read resources. See the [MCP routes reference](https://mastra.ai/reference/server/routes) for the full list. These paths use the default `/api` prefix.
+
+The `POST /api/mcp/:serverId/tools/:toolId/execute` route calls `executeTool()` directly, without a protocol client. With a Mastra FGA provider configured, `MCPServer.executeTool()` enforces tool execution permission using the user in `requestContext`. The REST tool list also filters tools through FGA. These permission checks don't replace route authentication.
+
+Built-in authentication for these routes depends on `server.auth`. Without it, `requiresAuth: true` doesn't enforce authentication. Custom middleware that checks only the `/mcp` or `/sse` transport paths leaves the REST routes open. If you use custom middleware instead of `server.auth`, default-deny `/api/mcp/*` and allow access only after authentication.
+
 ### Pass verified identity to tools
 
 When a Mastra server handles an MCP request, its auth bridge preserves an existing `req.auth`. Otherwise, it uses `server.mcpOptions.setRequestAuth` when configured, or builds `authInfo` from the request context. With the default bridge, the authenticated user is available in `authInfo.extra.user`.
@@ -121,9 +129,10 @@ Keep access tokens, refresh tokens, and service credentials outside model-visibl
 
 - [ ] **Validate tokens:** Configure validation for your issuer, including audience and expiry checks, and confirm an unvalidated token is rejected.
 - [ ] **Challenge missing tokens:** Confirm every protected server path returns `401` without a bearer token.
+- [ ] **Protect MCP REST routes:** If you don't use `server.auth`, confirm `/api/mcp/:serverId/tools*`, `/api/mcp/:serverId/resources*`, and `/api/mcp/v0/servers*` aren't reachable without authentication. Use your configured API prefix if it differs from `/api`.
 - [ ] **Isolate users:** Confirm one user's provider, connection, and stored credentials aren't reused for another user.
 - [ ] **Bind credentials to the issuer:** Confirm registration and tokens aren't reused when the authorization server changes.
-- [ ] **Deny unauthorized operations:** Confirm a caller without permission is denied `tools/call`, including for a tool it never listed.
+- [ ] **Deny unauthorized operations:** Confirm a caller without permission is denied both `tools/call` and `POST /api/mcp/:serverId/tools/:toolId/execute`, including for a tool it never listed.
 - [ ] **Scope records to the caller:** Confirm record lookups resolve the tenant from trusted server context rather than tool arguments.
 - [ ] **Keep tokens at their audience:** Confirm upstream calls use separate credentials and never forward the MCP token.
 - [ ] **Keep secrets out of model data:** Confirm tokens and credentials stay out of instructions, tool arguments, and tool results.

package/.docs/docs/server/middleware.md

@@ -86,6 +86,10 @@ Generated servers pass `server.apiPrefix` to the Hono adapter's [`prefix` constr
 
 This approach can't block routes declared public with `requiresAuth: false`, because Mastra skips user middleware for those routes. With a non-Hono server adapter, register equivalent middleware through the server framework instead.
 
+During `mastra dev`, inspect the full built-in route list, including MCP routes, in the [OpenAPI specification](http://localhost:4111/api/openapi.json). See the [server overview](https://mastra.ai/docs/server/overview) for API exploration and production settings.
+
+If you use middleware for authentication without `server.auth`, prefer default-deny middleware that authenticates requests before allowing access, rather than enumerating protected paths. Include the full API prefix so REST routes alongside MCP transports are covered.
+
 ### Using `RequestContext`
 
 You can populate `RequestContext` in a runtime server middleware by extracting information from the request. In this example, the `temperature-unit` is set based on the Cloudflare `CF-IPCountry` header to ensure responses match the user's locale.

package/.docs/reference/server/routes.md

@@ -542,12 +542,20 @@ Returns the persisted experiment result row.
 
 ## MCP
 
-| Method | Path                               | Description        |
-| ------ | ---------------------------------- | ------------------ |
-| `GET`  | `/api/mcp/servers`                 | List MCP servers   |
-| `GET`  | `/api/mcp/servers/:serverId/tools` | List server tools  |
-| `POST` | `/api/mcp/:serverId`               | MCP HTTP transport |
-| `GET`  | `/api/mcp/:serverId/sse`           | MCP SSE transport  |
+| Method | Path                                       | Description              |
+| ------ | ------------------------------------------ | ------------------------ |
+| `GET`  | `/api/mcp/v0/servers`                      | List MCP servers         |
+| `GET`  | `/api/mcp/v0/servers/:id`                  | Get server details       |
+| `GET`  | `/api/mcp/:serverId/tools`                 | List server tools        |
+| `GET`  | `/api/mcp/:serverId/tools/:toolId`         | Get tool details         |
+| `POST` | `/api/mcp/:serverId/tools/:toolId/execute` | Execute a tool           |
+| `GET`  | `/api/mcp/:serverId/resources`             | List server resources    |
+| `POST` | `/api/mcp/:serverId/resources/read`        | Read a resource          |
+| `ALL`  | `/api/mcp/:serverId/mcp`                   | MCP HTTP transport       |
+| `ALL`  | `/api/mcp/:serverId/sse`                   | Legacy MCP SSE transport |
+| `POST` | `/api/mcp/:serverId/messages`              | Legacy MCP SSE messages  |
+
+All MCP routes declare `requiresAuth: true`. Authentication is enforced only when `server.auth` is configured. Paths use the default `/api` prefix. The legacy SSE routes return `404` for MCP v2 servers.
 
 ## Responses API
 

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

@@ -456,7 +456,7 @@ getToolInfo(toolId: string): ToolInfo | undefined
 
 ### `executeTool()`
 
-Runs a tool without a protocol client, which is how the Mastra REST route `POST /api/mcp/:serverId/tools/:toolId/execute` and Studio invoke tools.
+Runs a tool without a protocol client, which is how the Mastra REST route `POST /api/mcp/:serverId/tools/:toolId/execute` and Studio invoke tools. See [authentication for registered MCP routes](https://mastra.ai/docs/guides/mcp-authentication-authorization) and the [MCP routes reference](https://mastra.ai/reference/server/routes).
 
 ```typescript
 async executeTool(

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mastra/mcp-docs-server",
-  "version": "1.3.8-alpha.5",
+  "version": "1.3.8-alpha.7",
   "description": "MCP server for accessing Mastra.ai documentation, changelogs, and news.",
   "type": "module",
   "main": "dist/index.js",
@@ -26,7 +26,7 @@
     "@mastra/mcp-legacy": "npm:@mastra/mcp@^1.18.0",
     "local-pkg": "^1.1.2",
     "zod": "^4.6.4",
-    "@mastra/core": "1.78.0-alpha.4",
+    "@mastra/core": "1.78.0-alpha.5",
     "@mastra/mcp": "^2.4.1-alpha.0"
   },
   "devDependencies": {
@@ -44,8 +44,8 @@
     "typescript": "^7.0.2",
     "vitest": "4.1.11",
     "@internal/lint": "0.0.143",
-    "@internal/types-builder": "0.0.118",
-    "@mastra/core": "1.78.0-alpha.4"
+    "@mastra/core": "1.78.0-alpha.5",
+    "@internal/types-builder": "0.0.118"
   },
   "homepage": "https://mastra.ai",
   "repository": {