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

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 (13) hide show
  1. package/.docs/docs/guides/mcp-authentication-authorization.md +10 -1
  2. package/.docs/docs/server/middleware.md +4 -0
  3. package/.docs/models/gateways/netlify.md +2 -1
  4. package/.docs/models/index.md +1 -1
  5. package/.docs/models/providers/aimlapi.md +3 -7
  6. package/.docs/models/providers/kilo.md +3 -3
  7. package/.docs/models/providers/llmgateway-providers.md +3 -1
  8. package/.docs/models/providers/llmgateway.md +1 -1
  9. package/.docs/models/providers/nvidia.md +1 -1
  10. package/.docs/models/providers/wandb.md +1 -1
  11. package/.docs/reference/server/routes.md +14 -6
  12. package/.docs/reference/tools/mcp-server.md +1 -1
  13. package/package.json +4 -4
package/.docs/docs/guides/mcp-authentication-authorization.md CHANGED
@@ -93,6 +93,14 @@ Configure validation appropriate to your issuer, including audience and expiry c
93
93
 
94
94
  Protecting Mastra routes with `server.auth` and providing interoperable OAuth discovery are different tasks. Don't assume configuring one supplies the other.
95
95
 
96
+ ### Routes Mastra registers for an MCP server
97
+
98
+ 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.
99
+
100
+ 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.
101
+
102
+ 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.
103
+
96
104
  ### Pass verified identity to tools
97
105
 
98
106
  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
121
129
 
122
130
  - [ ] **Validate tokens:** Configure validation for your issuer, including audience and expiry checks, and confirm an unvalidated token is rejected.
123
131
  - [ ] **Challenge missing tokens:** Confirm every protected server path returns `401` without a bearer token.
132
+ - [ ] **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`.
124
133
  - [ ] **Isolate users:** Confirm one user's provider, connection, and stored credentials aren't reused for another user.
125
134
  - [ ] **Bind credentials to the issuer:** Confirm registration and tokens aren't reused when the authorization server changes.
126
- - [ ] **Deny unauthorized operations:** Confirm a caller without permission is denied `tools/call`, including for a tool it never listed.
135
+ - [ ] **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.
127
136
  - [ ] **Scope records to the caller:** Confirm record lookups resolve the tenant from trusted server context rather than tool arguments.
128
137
  - [ ] **Keep tokens at their audience:** Confirm upstream calls use separate credentials and never forward the MCP token.
129
138
  - [ ] **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 CHANGED
@@ -86,6 +86,10 @@ Generated servers pass `server.apiPrefix` to the Hono adapter's [`prefix` constr
86
86
 
87
87
  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.
88
88
 
89
+ 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.
90
+
91
+ 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.
92
+
89
93
  ### Using `RequestContext`
90
94
 
91
95
  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/models/gateways/netlify.md CHANGED
@@ -4,7 +4,7 @@
4
4
 
5
5
  # Netlify
6
6
 
7
- Netlify AI Gateway provides unified access to multiple providers with built-in caching and observability. Access 275 models through Mastra's model router.
7
+ Netlify AI Gateway provides unified access to multiple providers with built-in caching and observability. Access 276 models through Mastra's model router.
8
8
 
9
9
  Learn more in the [Netlify documentation](https://docs.netlify.com/build/ai-gateway/overview/).
10
10
 
@@ -312,5 +312,6 @@ ANTHROPIC_API_KEY=ant-...
312
312
  | `openrouter/z-ai/glm-5.3` |
313
313
  | `openrouter/z-ai/glm-5.3-flash` |
314
314
  | `typesafe/jev-1.13.0` |
315
+ | `typesafe/jev-1.14.0` |
315
316
  | `typesafe/jev-latest` |
316
317
  | `typesafe/jev-preview` |
package/.docs/models/index.md CHANGED
@@ -4,7 +4,7 @@
4
4
 
5
5
  # Model Providers
6
6
 
7
- Mastra provides a unified interface for working with LLMs across multiple providers, giving you access to 8152 models from 217 providers through a single API.
7
+ Mastra provides a unified interface for working with LLMs across multiple providers, giving you access to 8151 models from 217 providers through a single API.
8
8
 
9
9
  ## Features
10
10
 
package/.docs/models/providers/aimlapi.md CHANGED
@@ -4,7 +4,7 @@
4
4
 
5
5
  # ![AI/ML API logo](https://models.dev/logos/aimlapi.svg)AI/ML API
6
6
 
7
- Access 181 AI/ML API models through Mastra's model router. Authentication is handled automatically using the `AIMLAPI_API_KEY` environment variable.
7
+ Access 177 AI/ML API models through Mastra's model router. Authentication is handled automatically using the `AIMLAPI_API_KEY` environment variable.
8
8
 
9
9
  Learn more in the [AI/ML API documentation](https://docs.aimlapi.com).
10
10
 
@@ -41,12 +41,8 @@ for await (const chunk of stream) {
41
41
  | `aimlapi/aion-labs/aion-rp-llama-3.1-8b` | 33K | | | | | | $1 | $2 |
42
42
  | `aimlapi/alibaba/qwen-max` | 32K | | | | | | $2 | $8 |
43
43
  | `aimlapi/alibaba/qwen-plus` | 131K | | | | | | $0.52 | $2 |
44
- | `aimlapi/alibaba/qwen3-coder-480b-a35b-instruct` | 262K | | | | | | $2 | $10 |
45
- | `aimlapi/alibaba/qwen3-max` | 262K | | | | | | $2 | $8 |
46
- | `aimlapi/alibaba/qwen3-max-preview` | 252K | | | | | | $2 | $8 |
47
- | `aimlapi/alibaba/qwen3-next-80b-a3b-instruct` | 129K | | | | | | $0.20 | $2 |
48
- | `aimlapi/alibaba/qwen3-vl-flash` | 262K | | | | | | $0.07 | $0.52 |
49
- | `aimlapi/alibaba/qwen3.6-max-preview` | 262K | | | | | | $0.65 | $4 |
44
+ | `aimlapi/alibaba/qwen3-coder-480b-a35b-instruct` | 262K | | | | | | $1 | $7 |
45
+ | `aimlapi/alibaba/qwen3-next-80b-a3b-instruct` | 129K | | | | | | $0.21 | $2 |
50
46
  | `aimlapi/alibaba/qwen3.8-2.4t-a95b` | 262K | | | | | | $3 | $9 |
51
47
  | `aimlapi/alibaba/qwen3.8-27b` | 262K | | | | | | $0.62 | $4 |
52
48
  | `aimlapi/alibaba/qwen3.8-flash` | 1.0M | | | | | | $0.21 | $0.61 |
package/.docs/models/providers/kilo.md CHANGED
@@ -47,7 +47,7 @@ for await (const chunk of stream) {
47
47
  | `kilo/~deepseek/deepseek-v4-flash-latest` | 1.0M | | | | | | $0.01 | $0.58 |
48
48
  | `kilo/~google/gemini-flash-latest` | 1.0M | | | | | | $0.75 | $4 |
49
49
  | `kilo/~google/gemini-pro-latest` | 1.0M | | | | | | $2 | $12 |
50
- | `kilo/~moonshotai/kimi-latest` | 1.0M | | | | | | $0.40 | $14 |
50
+ | `kilo/~moonshotai/kimi-latest` | 1.0M | | | | | | $0.49 | $15 |
51
51
  | `kilo/~openai/gpt-astra-latest` | 1.1M | | | | | | $10 | $50 |
52
52
  | `kilo/~openai/gpt-luna-latest` | 1.1M | | | | | | $0.10 | $0.50 |
53
53
  | `kilo/~openai/gpt-mini-latest` | 400K | | | | | | $0.75 | $5 |
@@ -207,7 +207,7 @@ for await (const chunk of stream) {
207
207
  | `kilo/mistralai/mistral-small-24b-instruct-2501` | 33K | | | | | | $0.05 | $0.08 |
208
208
  | `kilo/mistralai/mistral-small-2603` | 262K | | | | | | $0.15 | $0.60 |
209
209
  | `kilo/mistralai/mistral-small-3.1-24b-instruct` | 128K | | | | | | $0.35 | $0.56 |
210
- | `kilo/mistralai/mistral-small-3.2-24b-instruct` | 256K | | | | | | $0.10 | $0.30 |
210
+ | `kilo/mistralai/mistral-small-3.2-24b-instruct` | 128K | | | | | | $0.10 | $0.30 |
211
211
  | `kilo/mistralai/mixtral-8x22b-instruct` | 66K | | | | | | $2 | $6 |
212
212
  | `kilo/mistralai/voxtral-small-24b-2507` | 33K | | | | | | $0.10 | $0.30 |
213
213
  | `kilo/moonshotai/kimi-k2` | 131K | | | | | | $0.57 | $2 |
@@ -345,7 +345,7 @@ for await (const chunk of stream) {
345
345
  | `kilo/qwen/qwen3.5-plus-02-15` | 1.0M | | | | | | $0.26 | $2 |
346
346
  | `kilo/qwen/qwen3.5-plus-20260420` | 1.0M | | | | | | $0.30 | $2 |
347
347
  | `kilo/qwen/qwen3.6-27b` | 262K | | | | | | $0.45 | $3 |
348
- | `kilo/qwen/qwen3.6-35b-a3b` | 262K | | | | | | $0.10 | $0.95 |
348
+ | `kilo/qwen/qwen3.6-35b-a3b` | 262K | | | | | | $0.15 | $1 |
349
349
  | `kilo/qwen/qwen3.6-flash` | 1.0M | | | | | | $0.19 | $1 |
350
350
  | `kilo/qwen/qwen3.6-plus` | 1.0M | | | | | | $0.33 | $2 |
351
351
  | `kilo/qwen/qwen3.7-flash` | 1.0M | | | | | | $0.03 | $0.13 |
package/.docs/models/providers/llmgateway-providers.md CHANGED
@@ -4,7 +4,7 @@
4
4
 
5
5
  # ![LLM Gateway logo](https://models.dev/logos/llmgateway-providers.svg)LLM Gateway
6
6
 
7
- Access 437 LLM Gateway models through Mastra's model router. Authentication is handled automatically using the `LLMGATEWAY_API_KEY` environment variable.
7
+ Access 439 LLM Gateway models through Mastra's model router. Authentication is handled automatically using the `LLMGATEWAY_API_KEY` environment variable.
8
8
 
9
9
  Learn more in the [LLM Gateway documentation](https://llmgateway.io/docs).
10
10
 
@@ -178,11 +178,13 @@ for await (const chunk of stream) {
178
178
  | `llmgateway-providers/cerebras/gpt-oss-120b` | 131K | | | | | | $0.35 | $0.75 |
179
179
  | `llmgateway-providers/cerebras/llama-3.3-70b-instruct` | 128K | | | | | | $0.85 | $1 |
180
180
  | `llmgateway-providers/cerebras/qwen3-235b-a22b-instruct-2507` | 262K | | | | | | $0.60 | $1 |
181
+ | `llmgateway-providers/consensusprotocol/deepseek-v4-flash` | 1.0M | | | | | | $0.10 | $0.20 |
181
182
  | `llmgateway-providers/consensusprotocol/deepseek-v4.1-flash` | 1.0M | | | | | | $0.15 | $0.55 |
182
183
  | `llmgateway-providers/consensusprotocol/gemma-4-31b-it` | 262K | | | | | | $0.10 | $0.25 |
183
184
  | `llmgateway-providers/consensusprotocol/glm-5.3-flash` | 1.0M | | | | | | $0.10 | $0.25 |
184
185
  | `llmgateway-providers/consensusprotocol/gpt-oss-20b` | 128K | | | | | | $0.04 | $0.19 |
185
186
  | `llmgateway-providers/consensusprotocol/mimo-v2.6-flash` | 1.0M | | | | | | $0.12 | $0.25 |
187
+ | `llmgateway-providers/consensusprotocol/minimax-m3` | 1.0M | | | | | | $0.28 | $1 |
186
188
  | `llmgateway-providers/consensusprotocol/Qwen3.8-27B` | 262K | | | | | | $0.08 | $0.35 |
187
189
  | `llmgateway-providers/deepinfra/deepseek-v3.2` | 160K | | | | | | $0.26 | $0.38 |
188
190
  | `llmgateway-providers/deepinfra/deepseek-v4-flash` | 1.0M | | | | | | $0.08 | $0.18 |
package/.docs/models/providers/llmgateway.md CHANGED
@@ -185,7 +185,7 @@ for await (const chunk of stream) {
185
185
  | `llmgateway/minimax-m2.5-highspeed` | 205K | | | | | | $0.60 | $2 |
186
186
  | `llmgateway/minimax-m2.7` | 205K | | | | | | $0.08 | $0.32 |
187
187
  | `llmgateway/minimax-m2.7-highspeed` | 205K | | | | | | $0.60 | $2 |
188
- | `llmgateway/minimax-m3` | 1.0M | | | | | | $0.30 | $1 |
188
+ | `llmgateway/minimax-m3` | 1.0M | | | | | | $0.28 | $1 |
189
189
  | `llmgateway/minimax-text-01` | 1.0M | | | | | | $0.20 | $1 |
190
190
  | `llmgateway/ministral-14b-2512` | 262K | | | | | | $0.20 | $0.20 |
191
191
  | `llmgateway/ministral-3b-2512` | 131K | | | | | | $0.10 | $0.10 |
package/.docs/models/providers/nvidia.md CHANGED
@@ -73,10 +73,10 @@ for await (const chunk of stream) {
73
73
  | `nvidia/nvidia/llama-nemotron-rerank-vl-1b-v2` | 128K | | | | | | — | — |
74
74
  | `nvidia/nvidia/magpie-tts-zeroshot` | — | | | | | | — | — |
75
75
  | `nvidia/nvidia/nemotron-3-nano-omni-30b-a3b-reasoning` | 256K | | | | | | — | — |
76
- | `nvidia/nvidia/nemotron-3-super-120b-a12b` | 262K | | | | | | $0.20 | $0.80 |
77
76
  | `nvidia/nvidia/nemotron-3-ultra-550b-a55b` | 1.0M | | | | | | $0.50 | $3 |
78
77
  | `nvidia/nvidia/nemotron-3.5-content-safety` | 128K | | | | | | — | — |
79
78
  | `nvidia/nvidia/nemotron-3.5-lightning-30b-a3b` | 262K | | | | | | — | — |
79
+ | `nvidia/nvidia/nemotron-3.5-super-vl-120b-a12b` | 1.0M | | | | | | — | — |
80
80
  | `nvidia/nvidia/nemotron-voicechat` | 128K | | | | | | — | — |
81
81
  | `nvidia/nvidia/nv-embed-v1` | 33K | | | | | | — | — |
82
82
  | `nvidia/nvidia/nv-embedcode-7b-v1` | 33K | | | | | | — | — |
package/.docs/models/providers/wandb.md CHANGED
@@ -41,7 +41,7 @@ for await (const chunk of stream) {
41
41
  | `wandb/deepseek-ai/DeepSeek-V3.1` | 161K | | | | | | $0.55 | $2 |
42
42
  | `wandb/deepseek-ai/DeepSeek-V4-Flash-0731` | 262K | | | | | | $0.13 | $0.28 |
43
43
  | `wandb/deepseek-ai/DeepSeek-V4-Pro-0813` | 1.0M | | | | | | $1 | $4 |
44
- | `wandb/deepseek-ai/DeepSeek-V4.1-Flash` | 1.0M | | | | | | $0.20 | $0.65 |
44
+ | `wandb/deepseek-ai/DeepSeek-V4.1-Flash` | 1.0M | | | | | | $0.15 | $0.65 |
45
45
  | `wandb/google/gemma-4-26B-A4B-it` | 262K | | | | | | $0.10 | $0.30 |
46
46
  | `wandb/google/gemma-4-31B-it` | 262K | | | | | | $0.10 | $0.34 |
47
47
  | `wandb/ibm-granite/granite-4.2-8b` | 131K | | | | | | $0.10 | $0.15 |
package/.docs/reference/server/routes.md CHANGED
@@ -542,12 +542,20 @@ Returns the persisted experiment result row.
542
542
 
543
543
  ## MCP
544
544
 
545
- | Method | Path | Description |
546
- | ------ | ---------------------------------- | ------------------ |
547
- | `GET` | `/api/mcp/servers` | List MCP servers |
548
- | `GET` | `/api/mcp/servers/:serverId/tools` | List server tools |
549
- | `POST` | `/api/mcp/:serverId` | MCP HTTP transport |
550
- | `GET` | `/api/mcp/:serverId/sse` | MCP SSE transport |
545
+ | Method | Path | Description |
546
+ | ------ | ------------------------------------------ | ------------------------ |
547
+ | `GET` | `/api/mcp/v0/servers` | List MCP servers |
548
+ | `GET` | `/api/mcp/v0/servers/:id` | Get server details |
549
+ | `GET` | `/api/mcp/:serverId/tools` | List server tools |
550
+ | `GET` | `/api/mcp/:serverId/tools/:toolId` | Get tool details |
551
+ | `POST` | `/api/mcp/:serverId/tools/:toolId/execute` | Execute a tool |
552
+ | `GET` | `/api/mcp/:serverId/resources` | List server resources |
553
+ | `POST` | `/api/mcp/:serverId/resources/read` | Read a resource |
554
+ | `ALL` | `/api/mcp/:serverId/mcp` | MCP HTTP transport |
555
+ | `ALL` | `/api/mcp/:serverId/sse` | Legacy MCP SSE transport |
556
+ | `POST` | `/api/mcp/:serverId/messages` | Legacy MCP SSE messages |
557
+
558
+ 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.
551
559
 
552
560
  ## Responses API
553
561
 
package/.docs/reference/tools/mcp-server.md CHANGED
@@ -456,7 +456,7 @@ getToolInfo(toolId: string): ToolInfo | undefined
456
456
 
457
457
  ### `executeTool()`
458
458
 
459
- 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.
459
+ 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).
460
460
 
461
461
  ```typescript
462
462
  async executeTool(
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@mastra/mcp-docs-server",
3
- "version": "1.3.8-alpha.4",
3
+ "version": "1.3.8-alpha.7",
4
4
  "description": "MCP server for accessing Mastra.ai documentation, changelogs, and news.",
5
5
  "type": "module",
6
6
  "main": "dist/index.js",
@@ -26,7 +26,7 @@
26
26
  "@mastra/mcp-legacy": "npm:@mastra/mcp@^1.18.0",
27
27
  "local-pkg": "^1.1.2",
28
28
  "zod": "^4.6.4",
29
- "@mastra/core": "1.78.0-alpha.3",
29
+ "@mastra/core": "1.78.0-alpha.5",
30
30
  "@mastra/mcp": "^2.4.1-alpha.0"
31
31
  },
32
32
  "devDependencies": {
@@ -43,9 +43,9 @@
43
43
  "tsx": "^4.23.1",
44
44
  "typescript": "^7.0.2",
45
45
  "vitest": "4.1.11",
46
- "@internal/types-builder": "0.0.118",
47
46
  "@internal/lint": "0.0.143",
48
- "@mastra/core": "1.78.0-alpha.3"
47
+ "@mastra/core": "1.78.0-alpha.5",
48
+ "@internal/types-builder": "0.0.118"
49
49
  },
50
50
  "homepage": "https://mastra.ai",
51
51
  "repository": {