@mastra/mcp-docs-server 1.2.27 → 1.2.28-alpha.1
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.
- package/.docs/docs/connections/mcp.md +15 -9
- package/.docs/docs/server/server-adapters.md +16 -18
- package/.docs/models/gateways/openrouter.md +1 -2
- package/.docs/models/index.md +1 -1
- package/.docs/models/providers/crossmodel.md +4 -1
- package/.docs/models/providers/kilo.md +4 -5
- package/.docs/models/providers/llmgateway-providers.md +3 -1
- package/.docs/models/providers/llmgateway.md +3 -1
- package/.docs/models/providers/nano-gpt.md +7 -4
- package/.docs/models/providers/opencode.md +0 -1
- package/.docs/reference/configuration.md +10 -6
- package/.docs/reference/core/getMCPServer.md +6 -10
- package/.docs/reference/server/elysia-adapter.md +2 -2
- package/.docs/reference/server/express-adapter.md +1 -1
- package/.docs/reference/server/fastify-adapter.md +1 -1
- package/.docs/reference/server/hono-adapter.md +1 -1
- package/.docs/reference/server/koa-adapter.md +1 -1
- package/.docs/reference/server/nestjs-adapter.md +0 -2
- package/.docs/reference/tools/mcp-client.md +77 -276
- package/.docs/reference/tools/mcp-server.md +205 -537
- package/package.json +3 -3
|
@@ -6,7 +6,9 @@
|
|
|
6
6
|
|
|
7
7
|
Mastra supports the [Model Context Protocol (MCP)](https://modelcontextprotocol.io/introduction), an open standard for connecting AI agents to external tools and resources.
|
|
8
8
|
|
|
9
|
-
Use [`MCPClient`](https://mastra.ai/reference/tools/mcp-client) to connect to MCP servers. Use [`MCPServer`](https://mastra.ai/reference/tools/mcp-server) to expose Mastra agents, tools, workflows, prompts, and resources to other MCP-compatible systems.
|
|
9
|
+
Use [`MCPClient`](https://mastra.ai/reference/tools/mcp-client) to connect to MCP servers. Use [`MCPServer`](https://mastra.ai/reference/tools/mcp-server) to expose Mastra agents, tools, workflows, prompts, and resources to other MCP-compatible systems. Both speak the MCP `2026-07-28` revision over stdio and Streamable HTTP.
|
|
10
|
+
|
|
11
|
+
> **Note:** Upgrading from `@mastra/mcp` 1.x? See the [migration guide](https://mastra.ai/reference/migrations/mcp-v2).
|
|
10
12
|
|
|
11
13
|
## Connect to MCP servers
|
|
12
14
|
|
|
@@ -158,14 +160,14 @@ Visit the [MCPClient security reference](https://mastra.ai/reference/tools/mcp-c
|
|
|
158
160
|
|
|
159
161
|
Registries provide hosted or packaged MCP servers. The client configuration above works with registry endpoints and commands.
|
|
160
162
|
|
|
161
|
-
| Registry | Connection
|
|
162
|
-
| ----------------------------------------------- |
|
|
163
|
-
| [Klavis AI](https://klavis.ai) | Hosted HTTP
|
|
164
|
-
| [mcp.run](https://www.mcp.run/) | Signed
|
|
165
|
-
| [Composio](https://mcp.composio.dev) | Hosted
|
|
166
|
-
| [Smithery](https://smithery.ai) | CLI or hosted URL
|
|
167
|
-
| [Apify](https://mcp.apify.com) | Hosted HTTP
|
|
168
|
-
| [Ampersand](https://docs.withampersand.com/mcp) |
|
|
163
|
+
| Registry | Connection | Notes |
|
|
164
|
+
| ----------------------------------------------- | ------------------- | --------------------------------------------- |
|
|
165
|
+
| [Klavis AI](https://klavis.ai) | Hosted HTTP | Enterprise authentication and managed servers |
|
|
166
|
+
| [mcp.run](https://www.mcp.run/) | Signed hosted URL | Treat the profile URL as a secret |
|
|
167
|
+
| [Composio](https://mcp.composio.dev) | Hosted URL | URLs are often tied to one user account |
|
|
168
|
+
| [Smithery](https://smithery.ai) | CLI or hosted URL | Run local packages through `npx` |
|
|
169
|
+
| [Apify](https://mcp.apify.com) | Hosted HTTP | Authenticate with an Apify API token |
|
|
170
|
+
| [Ampersand](https://docs.withampersand.com/mcp) | Hosted URL or stdio | Connect to configured SaaS integrations |
|
|
169
171
|
|
|
170
172
|
Store signed URLs, API keys, and tokens in environment variables. Follow the registry's documentation to obtain the endpoint, command, and credentials for each server.
|
|
171
173
|
|
|
@@ -202,6 +204,10 @@ export const mastra = new Mastra({
|
|
|
202
204
|
|
|
203
205
|
> **Authentication:** Protect HTTP MCP servers with OAuth middleware. Visit [OAuth protection](https://mastra.ai/reference/tools/mcp-server) for setup instructions.
|
|
204
206
|
|
|
207
|
+
Registered servers are served at `/api/mcp/:serverId/mcp` over Streamable HTTP. Every request is self-contained, so the same server runs unchanged on long-lived hosts and serverless platforms.
|
|
208
|
+
|
|
209
|
+
A tool that needs something from the user before it can finish calls `context.suspend()` with a payload and declares a `resumeSchema`. The server turns that into an `input_required` round and runs the tool again with the answer in `context.resumeData`. Clients answer those rounds with the `inputRequests` handler on their server definition. Visit [Asking the caller for input](https://mastra.ai/reference/tools/mcp-server) and [Answering input requests](https://mastra.ai/reference/tools/mcp-client).
|
|
210
|
+
|
|
205
211
|
Visit the [`MCPServer` reference](https://mastra.ai/reference/tools/mcp-server) for prompts, resources, transports, and other server options.
|
|
206
212
|
|
|
207
213
|
### Publish a stdio server package
|
|
@@ -755,14 +755,14 @@ The adapter reads these settings from `mastra.getServer()`:
|
|
|
755
755
|
|
|
756
756
|
These options are passed directly to the adapter constructor and aren't read from the Mastra config:
|
|
757
757
|
|
|
758
|
-
| Option | Description
|
|
759
|
-
| ----------------------- |
|
|
760
|
-
| `prefix` | Route path prefix
|
|
761
|
-
| `openapiPath` | OpenAPI spec endpoint
|
|
762
|
-
| `bodyLimitOptions` | Body size limit with custom error handler
|
|
763
|
-
| `streamOptions` | Stream redaction settings
|
|
764
|
-
| `customRouteAuthConfig` | Per-route auth overrides
|
|
765
|
-
| `mcpOptions` | MCP transport options (e.g., `
|
|
758
|
+
| Option | Description |
|
|
759
|
+
| ----------------------- | -------------------------------------------------------------------------------------- |
|
|
760
|
+
| `prefix` | Route path prefix |
|
|
761
|
+
| `openapiPath` | OpenAPI spec endpoint |
|
|
762
|
+
| `bodyLimitOptions` | Body size limit with custom error handler |
|
|
763
|
+
| `streamOptions` | Stream redaction settings |
|
|
764
|
+
| `customRouteAuthConfig` | Per-route auth overrides |
|
|
765
|
+
| `mcpOptions` | MCP transport options (e.g., `setRequestAuth` to control `context.mcp.extra.authInfo`) |
|
|
766
766
|
|
|
767
767
|
### Not used by adapters
|
|
768
768
|
|
|
@@ -781,19 +781,17 @@ When using adapters, configure these features directly with your framework. For
|
|
|
781
781
|
|
|
782
782
|
Server adapters register MCP (Model Context Protocol) routes during `registerRoutes()` when MCP servers are configured in your Mastra instance. MCP allows external tools and services to connect to your Mastra server and interact with your agents.
|
|
783
783
|
|
|
784
|
-
|
|
784
|
+
Each server is exposed at `/api/mcp/:serverId/mcp` over Streamable HTTP. Every request is self-contained, so the routes work unchanged in serverless environments like Cloudflare Workers or Vercel Edge.
|
|
785
785
|
|
|
786
|
-
|
|
787
|
-
|
|
788
|
-
For serverless environments like Cloudflare Workers or Vercel Edge, enable stateless mode via `mcpOptions`.
|
|
789
|
-
|
|
790
|
-
When using the Mastra deployer (the standard `mastra dev` / `mastra build` path), set `mcpOptions` in your server config:
|
|
786
|
+
Pass `mcpOptions` to control how the authenticated principal reaches tools. When using the Mastra deployer (the standard `mastra dev` / `mastra build` path), set it in your server config:
|
|
791
787
|
|
|
792
788
|
```typescript
|
|
793
789
|
const mastra = new Mastra({
|
|
794
790
|
server: {
|
|
795
791
|
mcpOptions: {
|
|
796
|
-
|
|
792
|
+
setRequestAuth: (req, requestContext) => {
|
|
793
|
+
req.auth = requestContext.get('mcpAuth')
|
|
794
|
+
},
|
|
797
795
|
},
|
|
798
796
|
},
|
|
799
797
|
})
|
|
@@ -806,13 +804,13 @@ const server = new MastraServer({
|
|
|
806
804
|
app,
|
|
807
805
|
mastra,
|
|
808
806
|
mcpOptions: {
|
|
809
|
-
|
|
807
|
+
setRequestAuth: (req, requestContext) => {
|
|
808
|
+
req.auth = requestContext.get('mcpAuth')
|
|
809
|
+
},
|
|
810
810
|
},
|
|
811
811
|
})
|
|
812
812
|
```
|
|
813
813
|
|
|
814
|
-
When `serverless: true`, MCP HTTP requests run without session management, making them compatible with stateless execution environments.
|
|
815
|
-
|
|
816
814
|
See [MCP](https://mastra.ai/docs/connections/mcp) for configuration details and how to set up MCP servers.
|
|
817
815
|
|
|
818
816
|
## Related
|
|
@@ -4,7 +4,7 @@
|
|
|
4
4
|
|
|
5
5
|
# OpenRouter
|
|
6
6
|
|
|
7
|
-
OpenRouter aggregates models from multiple providers with enhanced features like rate limiting and failover. Access
|
|
7
|
+
OpenRouter aggregates models from multiple providers with enhanced features like rate limiting and failover. Access 375 models through Mastra's model router.
|
|
8
8
|
|
|
9
9
|
Learn more in the [OpenRouter documentation](https://openrouter.ai/models).
|
|
10
10
|
|
|
@@ -154,7 +154,6 @@ ANTHROPIC_API_KEY=ant-...
|
|
|
154
154
|
| `inclusionai/ling-3.0-flash-vl:free` |
|
|
155
155
|
| `inference-net/schematron-v2-small` |
|
|
156
156
|
| `inference-net/schematron-v2-turbo` |
|
|
157
|
-
| `kwaipilot/kat-coder-pro-v2` |
|
|
158
157
|
| `kwaipilot/kat-coder-pro-v2.5` |
|
|
159
158
|
| `liquid/lfm-2.5-2.6b:free` |
|
|
160
159
|
| `mancer/weaver` |
|
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
|
|
7
|
+
Mastra provides a unified interface for working with LLMs across multiple providers, giving you access to 7479 models from 210 providers through a single API.
|
|
8
8
|
|
|
9
9
|
## Features
|
|
10
10
|
|
|
@@ -4,7 +4,7 @@
|
|
|
4
4
|
|
|
5
5
|
# CrossModel
|
|
6
6
|
|
|
7
|
-
Access
|
|
7
|
+
Access 63 CrossModel models through Mastra's model router. Authentication is handled automatically using the `CROSSMODEL_API_KEY` environment variable.
|
|
8
8
|
|
|
9
9
|
Learn more in the [CrossModel documentation](https://www.crossmodel.ai/docs).
|
|
10
10
|
|
|
@@ -88,9 +88,12 @@ for await (const chunk of stream) {
|
|
|
88
88
|
| `crossmodel/x-ai/grok-4.3` | 1.0M | | | | | | $1 | $3 |
|
|
89
89
|
| `crossmodel/x-ai/grok-4.5` | 500K | | | | | | $2 | $6 |
|
|
90
90
|
| `crossmodel/x-ai/grok-4.6` | 500K | | | | | | $2 | $6 |
|
|
91
|
+
| `crossmodel/x-ai/grok-4.7` | 500K | | | | | | $2 | $6 |
|
|
91
92
|
| `crossmodel/x-ai/grok-build-0.1` | 256K | | | | | | $1 | $2 |
|
|
92
93
|
| `crossmodel/xiaomi/mimo-v2.5` | 1.0M | | | | | | $0.16 | $0.32 |
|
|
93
94
|
| `crossmodel/xiaomi/mimo-v2.5-pro` | 1.0M | | | | | | $0.47 | $0.94 |
|
|
95
|
+
| `crossmodel/xiaomi/mimo-v2.6-flash` | 1.0M | | | | | | $0.16 | $0.32 |
|
|
96
|
+
| `crossmodel/xiaomi/mimo-v2.6-pro` | 1.0M | | | | | | $0.47 | $0.94 |
|
|
94
97
|
| `crossmodel/z-ai/glm-4.7` | 200K | | | | | | $0.47 | $2 |
|
|
95
98
|
| `crossmodel/z-ai/glm-5` | 200K | | | | | | $0.60 | $3 |
|
|
96
99
|
| `crossmodel/z-ai/glm-5-turbo` | 200K | | | | | | $0.90 | $4 |
|
|
@@ -4,7 +4,7 @@
|
|
|
4
4
|
|
|
5
5
|
# Kilo Gateway
|
|
6
6
|
|
|
7
|
-
Access
|
|
7
|
+
Access 382 Kilo Gateway models through Mastra's model router. Authentication is handled automatically using the `KILO_API_KEY` environment variable.
|
|
8
8
|
|
|
9
9
|
Learn more in the [Kilo Gateway documentation](https://kilo.ai).
|
|
10
10
|
|
|
@@ -43,8 +43,8 @@ for await (const chunk of stream) {
|
|
|
43
43
|
| `kilo/~anthropic/claude-opus-latest` | 1.0M | | | | | | $5 | $25 |
|
|
44
44
|
| `kilo/~anthropic/claude-sonnet-latest` | 1.0M | | | | | | $2 | $10 |
|
|
45
45
|
| `kilo/~deepseek/deepseek-flash-latest` | 1.0M | | | | | | $0.12 | $0.48 |
|
|
46
|
-
| `kilo/~deepseek/deepseek-pro-latest` | 1.0M | | | | | | $0.
|
|
47
|
-
| `kilo/~deepseek/deepseek-v4-flash-latest` | 1.0M | | | | | | $0.03 | $
|
|
46
|
+
| `kilo/~deepseek/deepseek-pro-latest` | 1.0M | | | | | | $0.62 | $3 |
|
|
47
|
+
| `kilo/~deepseek/deepseek-v4-flash-latest` | 1.0M | | | | | | $0.03 | $1 |
|
|
48
48
|
| `kilo/~google/gemini-flash-latest` | 1.0M | | | | | | $0.75 | $4 |
|
|
49
49
|
| `kilo/~google/gemini-pro-latest` | 1.0M | | | | | | $2 | $12 |
|
|
50
50
|
| `kilo/~moonshotai/kimi-latest` | 1.0M | | | | | | $2 | $8 |
|
|
@@ -157,7 +157,6 @@ for await (const chunk of stream) {
|
|
|
157
157
|
| `kilo/kilo-auto/free` | 256K | | | | | | — | — |
|
|
158
158
|
| `kilo/kilo-auto/frontier` | 1.0M | | | | | | $5 | $25 |
|
|
159
159
|
| `kilo/kilo-auto/small` | 262K | | | | | | $0.05 | $0.40 |
|
|
160
|
-
| `kilo/kwaipilot/kat-coder-pro-v2` | 262K | | | | | | $0.30 | $1 |
|
|
161
160
|
| `kilo/kwaipilot/kat-coder-pro-v2.5` | 262K | | | | | | $0.74 | $3 |
|
|
162
161
|
| `kilo/liquid/lfm-2.5-2.6b:free` | 66K | | | | | | — | — |
|
|
163
162
|
| `kilo/mancer/weaver` | 8K | | | | | | $0.40 | $0.75 |
|
|
@@ -327,7 +326,7 @@ for await (const chunk of stream) {
|
|
|
327
326
|
| `kilo/qwen/qwen3-max` | 262K | | | | | | $0.78 | $4 |
|
|
328
327
|
| `kilo/qwen/qwen3-max-thinking` | 262K | | | | | | $0.78 | $4 |
|
|
329
328
|
| `kilo/qwen/qwen3-next-80b-a3b-instruct` | 262K | | | | | | $0.10 | $0.78 |
|
|
330
|
-
| `kilo/qwen/qwen3-next-80b-a3b-thinking` |
|
|
329
|
+
| `kilo/qwen/qwen3-next-80b-a3b-thinking` | 262K | | | | | | $0.15 | $1 |
|
|
331
330
|
| `kilo/qwen/qwen3-vl-235b-a22b-instruct` | 131K | | | | | | $0.26 | $1 |
|
|
332
331
|
| `kilo/qwen/qwen3-vl-235b-a22b-thinking` | 131K | | | | | | $0.40 | $4 |
|
|
333
332
|
| `kilo/qwen/qwen3-vl-30b-a3b-instruct` | 131K | | | | | | $0.13 | $0.52 |
|
|
@@ -4,7 +4,7 @@
|
|
|
4
4
|
|
|
5
5
|
# LLM Gateway
|
|
6
6
|
|
|
7
|
-
Access
|
|
7
|
+
Access 408 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
|
|
|
@@ -428,6 +428,8 @@ for await (const chunk of stream) {
|
|
|
428
428
|
| `llmgateway-providers/xai/grok-build-0-1` | 256K | | | | | | $1 | $2 |
|
|
429
429
|
| `llmgateway-providers/xiaomi/mimo-v2.5` | 1.0M | | | | | | $0.14 | $0.28 |
|
|
430
430
|
| `llmgateway-providers/xiaomi/mimo-v2.5-pro` | 1.0M | | | | | | $0.43 | $0.87 |
|
|
431
|
+
| `llmgateway-providers/xiaomi/mimo-v2.6-flash` | 1.0M | | | | | | $0.14 | $0.28 |
|
|
432
|
+
| `llmgateway-providers/xiaomi/mimo-v2.6-pro` | 1.0M | | | | | | $0.43 | $0.87 |
|
|
431
433
|
| `llmgateway-providers/zai/glm-4-32b-0414-128k` | 128K | | | | | | $0.10 | $0.10 |
|
|
432
434
|
| `llmgateway-providers/zai/glm-4.5` | 128K | | | | | | $0.60 | $2 |
|
|
433
435
|
| `llmgateway-providers/zai/glm-4.5-air` | 128K | | | | | | $0.20 | $1 |
|
|
@@ -4,7 +4,7 @@
|
|
|
4
4
|
|
|
5
5
|
# DevPass (LLM Gateway)
|
|
6
6
|
|
|
7
|
-
Access
|
|
7
|
+
Access 196 DevPass (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 [DevPass (LLM Gateway) documentation](https://llmgateway.io/docs).
|
|
10
10
|
|
|
@@ -164,6 +164,8 @@ for await (const chunk of stream) {
|
|
|
164
164
|
| `llmgateway/llama-4-scout-17b-instruct` | 131K | | | | | | $0.18 | $0.59 |
|
|
165
165
|
| `llmgateway/mimo-v2.5` | 1.0M | | | | | | $0.14 | $0.28 |
|
|
166
166
|
| `llmgateway/mimo-v2.5-pro` | 1.0M | | | | | | $0.43 | $0.87 |
|
|
167
|
+
| `llmgateway/mimo-v2.6-flash` | 1.0M | | | | | | $0.14 | $0.28 |
|
|
168
|
+
| `llmgateway/mimo-v2.6-pro` | 1.0M | | | | | | $0.43 | $0.87 |
|
|
167
169
|
| `llmgateway/minimax-m2` | 197K | | | | | | $0.20 | $1 |
|
|
168
170
|
| `llmgateway/minimax-m2.1` | 205K | | | | | | $0.27 | $1 |
|
|
169
171
|
| `llmgateway/minimax-m2.1-lightning` | 197K | | | | | | $0.12 | $0.48 |
|
|
@@ -4,7 +4,7 @@
|
|
|
4
4
|
|
|
5
5
|
# NanoGPT
|
|
6
6
|
|
|
7
|
-
Access
|
|
7
|
+
Access 580 NanoGPT models through Mastra's model router. Authentication is handled automatically using the `NANO_GPT_API_KEY` environment variable.
|
|
8
8
|
|
|
9
9
|
Learn more in the [NanoGPT documentation](https://docs.nano-gpt.com).
|
|
10
10
|
|
|
@@ -39,9 +39,9 @@ for await (const chunk of stream) {
|
|
|
39
39
|
| Model | Context | Tools | Reasoning | Image | Audio | Video | Input $/1M | Output $/1M |
|
|
40
40
|
| ---------------------------------------------------------------- | ------- | ----- | --------- | ----- | ----- | ----- | ---------- | ----------- |
|
|
41
41
|
| `nano-gpt/abacusai/Dracarys-72B-Instruct` | 33K | | | | | | $0.49 | $0.49 |
|
|
42
|
-
| `nano-gpt/abliteration-ai/abliterated-model` | 262K | | | | | | $
|
|
43
|
-
| `nano-gpt/abliteration-ai/abliterated-model-large` | 1.0M | | | | | | $
|
|
44
|
-
| `nano-gpt/abliteration-ai/abliterated-model-large-v2` | 1.0M | | | | | | $
|
|
42
|
+
| `nano-gpt/abliteration-ai/abliterated-model` | 262K | | | | | | $1 | $3 |
|
|
43
|
+
| `nano-gpt/abliteration-ai/abliterated-model-large` | 1.0M | | | | | | $3 | $5 |
|
|
44
|
+
| `nano-gpt/abliteration-ai/abliterated-model-large-v2` | 1.0M | | | | | | $3 | $5 |
|
|
45
45
|
| `nano-gpt/agnes-3.0-flash` | 524K | | | | | | $0.05 | $0.15 |
|
|
46
46
|
| `nano-gpt/aion-labs/aion-2.0` | 131K | | | | | | $0.80 | $2 |
|
|
47
47
|
| `nano-gpt/aion-labs/aion-3.0` | 131K | | | | | | $3 | $6 |
|
|
@@ -579,6 +579,9 @@ for await (const chunk of stream) {
|
|
|
579
579
|
| `nano-gpt/xiaomi/mimo-v2.5-pro` | 1.0M | | | | | | $0.43 | $0.87 |
|
|
580
580
|
| `nano-gpt/xiaomi/mimo-v2.5-pro:thinking` | 1.0M | | | | | | $0.43 | $0.87 |
|
|
581
581
|
| `nano-gpt/xiaomi/mimo-v2.5:thinking` | 1.0M | | | | | | $0.14 | $0.28 |
|
|
582
|
+
| `nano-gpt/xiaomi/mimo-v2.6-flash` | 1.0M | | | | | | $0.14 | $0.28 |
|
|
583
|
+
| `nano-gpt/xiaomi/mimo-v2.6-pro` | 1.0M | | | | | | $0.43 | $0.87 |
|
|
584
|
+
| `nano-gpt/xiaomi/mimo-v2.6-pro-ultraspeed` | 1.0M | | | | | | $4 | $9 |
|
|
582
585
|
| `nano-gpt/z-ai/glm-4.5` | 128K | | | | | | $0.30 | $1 |
|
|
583
586
|
| `nano-gpt/z-ai/GLM-4.5-Air` | 128K | | | | | | $0.12 | $0.80 |
|
|
584
587
|
| `nano-gpt/z-ai/GLM-4.5-Air:thinking` | 128K | | | | | | $0.12 | $0.80 |
|
|
@@ -96,7 +96,6 @@ for await (const chunk of stream) {
|
|
|
96
96
|
| `opencode/kimi-k2.7-code` | 262K | | | | | | $0.95 | $4 |
|
|
97
97
|
| `opencode/kimi-k3` | 1.0M | | | | | | $3 | $15 |
|
|
98
98
|
| `opencode/ling-3.0-flash-fin-free` | 262K | | | | | | — | — |
|
|
99
|
-
| `opencode/mimo-v2.5-free` | 200K | | | | | | — | — |
|
|
100
99
|
| `opencode/mimo-v2.6-flash-free` | 200K | | | | | | — | — |
|
|
101
100
|
| `opencode/minimax-m2.5` | 205K | | | | | | $0.30 | $1 |
|
|
102
101
|
| `opencode/minimax-m2.7` | 205K | | | | | | $0.30 | $1 |
|
|
@@ -660,12 +660,13 @@ export const mastra = new Mastra({
|
|
|
660
660
|
**Type:** `object`\
|
|
661
661
|
**Default:** `undefined`
|
|
662
662
|
|
|
663
|
-
|
|
663
|
+
Options applied to every MCP HTTP route. MCP requests are self-contained, so no session state is kept between them and the routes run unchanged in serverless environments (Cloudflare Workers, Vercel Edge, AWS Lambda, etc.).
|
|
664
664
|
|
|
665
|
-
| Property | Type
|
|
666
|
-
| -------------------- |
|
|
667
|
-
| `
|
|
668
|
-
| `
|
|
665
|
+
| Property | Type | Default | Description |
|
|
666
|
+
| -------------------- | ------------------------------------------------ | ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
667
|
+
| `setRequestAuth` | `(req, requestContext) => void \| Promise<void>` | `undefined` | Sets `req.auth` on the request handed to the MCP transport, which surfaces as `context.mcp.extra.authInfo` in tools. When omitted, the principal resolved by `server.auth` is bridged automatically. |
|
|
668
|
+
| `serverless` | `boolean` | `false` | Accepted for compatibility. Has no effect: every MCP request is already stateless. |
|
|
669
|
+
| `sessionIdGenerator` | `() => string` | `undefined` | Accepted for compatibility. Has no effect: MCP requests carry no session. |
|
|
669
670
|
|
|
670
671
|
```typescript
|
|
671
672
|
import { Mastra } from '@mastra/core'
|
|
@@ -673,7 +674,10 @@ import { Mastra } from '@mastra/core'
|
|
|
673
674
|
export const mastra = new Mastra({
|
|
674
675
|
server: {
|
|
675
676
|
mcpOptions: {
|
|
676
|
-
|
|
677
|
+
setRequestAuth: (req, requestContext) => {
|
|
678
|
+
const payload = requestContext.get('bearerPayload')
|
|
679
|
+
req.auth = { token: payload.token, clientId: payload.sub, scopes: [] }
|
|
680
|
+
},
|
|
677
681
|
},
|
|
678
682
|
},
|
|
679
683
|
})
|
|
@@ -38,15 +38,13 @@ const serverById = mastra.getMCPServerById('my-mcp-server')
|
|
|
38
38
|
|
|
39
39
|
**server** (`MCPServerBase | undefined`): The MCP server instance with the specified registry key, or undefined if not found.
|
|
40
40
|
|
|
41
|
-
##
|
|
41
|
+
## The `MCPServerBase` contract
|
|
42
42
|
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
The 1.x-only surfaces are marked `@deprecated` and are removed in the next major release of `@mastra/core`: `startSSE`, `startHonoSSE`, `MCPServerSSEOptions`, `MCPServerHonoSSEOptions`, `MCPServerHTTPOptions.options`, and on `context.mcp` the members `elicitation`, `extra.sendNotification` and `extra.sendRequest`.
|
|
43
|
+
Every registered server extends `MCPServerBase` from `@mastra/core/mcp`. The `MCPServer` class in `@mastra/mcp` implements it for the MCP `2026-07-28` protocol and sets `mcpVersion` to `2`. Tool execution, suspension, and the `context.mcp` shape described below are the parts of the contract a tool author sees. For the 1.x-only members that remain on the base class as deprecated stubs, see the [migration guide](https://mastra.ai/reference/migrations/mcp-v2).
|
|
46
44
|
|
|
47
45
|
### Tools that ask for input
|
|
48
46
|
|
|
49
|
-
|
|
47
|
+
An MCP server runs ordinary `createTool` definitions. A tool that needs something from the user before it can finish declares `suspendSchema` and `resumeSchema` and calls `suspend()`, exactly as it would for an agent or a workflow. Core reports the suspension as `{ status: 'suspended', suspendPayload, resumeSchema }` from `executeTool`. `MCPServer` turns that into an `input_required` round on the wire, and resumes the tool with the answer in `resumeData`.
|
|
50
48
|
|
|
51
49
|
```typescript
|
|
52
50
|
import { createTool } from '@mastra/core/tools'
|
|
@@ -69,19 +67,17 @@ const confirm = createTool({
|
|
|
69
67
|
})
|
|
70
68
|
```
|
|
71
69
|
|
|
72
|
-
On
|
|
70
|
+
On an MCP server and in direct execution, `suspend`, `resumeData` and `suspendPayload` sit at the top level of the tool context. Agents and workflows still nest them under `context.agent` and `context.workflow` until the next major release of `@mastra/core`. `resumeSchema` must be a flat object of primitive fields so it can be presented as an input form.
|
|
73
71
|
|
|
74
72
|
Each round is a separate request. `resumeData` carries only the current round's answer, validated against `resumeSchema`, and `suspendPayload` carries what the tool last suspended with. Because the framework never replays earlier rounds, handlers branch on explicit named phases, every round is re-authorized, and writes rely on domain-owned idempotency. `suspendPayload` is also handed back to tools resumed by agents and workflows.
|
|
75
73
|
|
|
76
74
|
### The `mcp` context
|
|
77
75
|
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
The 2026-07-28 protocol removed server-initiated requests, so on a 2.x server the deprecated members `elicitation.sendRequest`, `extra.sendRequest` and `extra.sendNotification` throw with a message naming the replacement instead of doing nothing. A 1.x server keeps providing them as before. To ask the user for input, call `context.suspend()` and read `context.resumeData`.
|
|
76
|
+
Tools receive `context.mcp` (`MCPToolExecutionContext`): `extra` with the request's `signal`, `requestId`, `authInfo` and `_meta`, plus `log(level, message, data?)`, `progress({ progress, total?, message? })` and `protocolVersion` (`'2026-07-28'`). To ask the user for input, call `context.suspend()` and read `context.resumeData`. Server-initiated requests don't exist in the protocol, so the deprecated `elicitation.sendRequest`, `extra.sendRequest` and `extra.sendNotification` members throw with a message naming the replacement.
|
|
81
77
|
|
|
82
78
|
### Registration and execution
|
|
83
79
|
|
|
84
|
-
Tools are registered on the Mastra instance
|
|
80
|
+
Tools are registered on the Mastra instance when the server is registered. `executeTool(toolId, args, context?)` returns `{ status: 'completed', output }` or, when the tool suspended, `{ status: 'suspended', suspendPayload, resumeSchema }` with `resumeSchema` as JSON Schema. The result has no failure variant: a tool that throws, or input or resume data that fails its schema, rejects the promise. The REST execution endpoint returns the suspended shape instead of pretending the tool finished, and accepts `resumeData` plus the echoed `suspendPayload` on the next call to continue the tool.
|
|
85
81
|
|
|
86
82
|
Registering another server under an occupied registry key keeps the existing instance. Registry keys and intrinsic server IDs remain distinct.
|
|
87
83
|
|
|
@@ -73,7 +73,7 @@ console.log('Server running on http://localhost:3000')
|
|
|
73
73
|
|
|
74
74
|
**taskStore** (`InMemoryTaskStore`): Task store for A2A (Agent-to-Agent) operations
|
|
75
75
|
|
|
76
|
-
**mcpOptions** (`MCPOptions`): MCP transport options
|
|
76
|
+
**mcpOptions** (`MCPOptions`): MCP transport options, such as setRequestAuth to control what tools see as context.mcp.extra.authInfo.
|
|
77
77
|
|
|
78
78
|
## Adding custom routes
|
|
79
79
|
|
|
@@ -179,7 +179,7 @@ Call `clearMastraOpenAPICache(server)` if you need to regenerate the cached docu
|
|
|
179
179
|
|
|
180
180
|
## MCP support
|
|
181
181
|
|
|
182
|
-
The Elysia adapter
|
|
182
|
+
The Elysia adapter serves each registered MCP server over Streamable HTTP at `/api/mcp/:serverId/mcp`.
|
|
183
183
|
|
|
184
184
|
## Manual initialization
|
|
185
185
|
|
|
@@ -74,7 +74,7 @@ app.listen(4111, () => {
|
|
|
74
74
|
|
|
75
75
|
**taskStore** (`InMemoryTaskStore`): Task store for A2A (Agent-to-Agent) operations
|
|
76
76
|
|
|
77
|
-
**mcpOptions** (`MCPOptions`): MCP transport options
|
|
77
|
+
**mcpOptions** (`MCPOptions`): MCP transport options, such as setRequestAuth to control what tools see as context.mcp.extra.authInfo.
|
|
78
78
|
|
|
79
79
|
## Differences from Hono
|
|
80
80
|
|
|
@@ -75,7 +75,7 @@ app.listen({ port: 3000 }, (err, address) => {
|
|
|
75
75
|
|
|
76
76
|
**taskStore** (`InMemoryTaskStore`): Task store for A2A (Agent-to-Agent) operations
|
|
77
77
|
|
|
78
|
-
**mcpOptions** (`MCPOptions`): MCP transport options
|
|
78
|
+
**mcpOptions** (`MCPOptions`): MCP transport options, such as setRequestAuth to control what tools see as context.mcp.extra.authInfo.
|
|
79
79
|
|
|
80
80
|
## Protecting raw routes
|
|
81
81
|
|
|
@@ -69,7 +69,7 @@ export default app
|
|
|
69
69
|
|
|
70
70
|
**taskStore** (`InMemoryTaskStore`): Task store for A2A (Agent-to-Agent) operations
|
|
71
71
|
|
|
72
|
-
**mcpOptions** (`MCPOptions`): MCP transport options
|
|
72
|
+
**mcpOptions** (`MCPOptions`): MCP transport options, such as setRequestAuth to control what tools see as context.mcp.extra.authInfo.
|
|
73
73
|
|
|
74
74
|
## Adding custom routes
|
|
75
75
|
|
|
@@ -74,7 +74,7 @@ app.listen(3000, () => {
|
|
|
74
74
|
|
|
75
75
|
**taskStore** (`InMemoryTaskStore`): Task store for A2A (Agent-to-Agent) operations
|
|
76
76
|
|
|
77
|
-
**mcpOptions** (`MCPOptions`): MCP transport options
|
|
77
|
+
**mcpOptions** (`MCPOptions`): MCP transport options, such as setRequestAuth to control what tools see as context.mcp.extra.authInfo.
|
|
78
78
|
|
|
79
79
|
## Error handling
|
|
80
80
|
|