@mastra/mcp-docs-server 1.2.17-alpha.16 → 1.2.17-alpha.18
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/acp.md +17 -5
- package/.docs/docs/connections/overview.md +1 -1
- package/.docs/docs/connections/sdk-agents.md +2 -0
- package/.docs/docs/harness/durable-agents.md +16 -0
- package/.docs/models/environment-variables.md +1 -0
- package/.docs/models/gateways/openrouter.md +1 -3
- package/.docs/models/gateways/vercel.md +19 -1
- package/.docs/models/index.md +1 -1
- package/.docs/models/providers/cloudflare-workers-ai.md +2 -1
- package/.docs/models/providers/deepinfra.md +2 -1
- package/.docs/models/providers/edenai.md +3 -1
- package/.docs/models/providers/kilo.md +2 -4
- package/.docs/models/providers/kosmik.md +73 -0
- package/.docs/models/providers/merge-gateway.md +2 -1
- package/.docs/models/providers/nano-gpt.md +4 -4
- package/.docs/models/providers/sakana.md +3 -2
- package/.docs/models/providers.md +1 -0
- package/.docs/reference/agents/generate.md +2 -0
- package/.docs/reference/agents/network.md +2 -0
- package/.docs/reference/client-js/agents.md +20 -0
- package/.docs/reference/processors/token-limiter-processor.md +4 -0
- package/.docs/reference/streaming/agents/stream.md +22 -0
- package/.docs/reference/tools/mcp-client.md +2 -0
- package/.docs/reference/tools/mcp-server.md +50 -2
- package/CHANGELOG.md +15 -0
- package/package.json +5 -5
|
@@ -4,7 +4,7 @@
|
|
|
4
4
|
|
|
5
5
|
Mastra supports the [Agent Client Protocol (ACP)](https://agentclientprotocol.com/overview/introduction) for running ACP-compatible coding agents from a Mastra agent. Use `@mastra/acp` to wrap a coding agent process as a Mastra tool or as a subagent.
|
|
6
6
|
|
|
7
|
-
ACP is useful for coding agents such as Claude Code, Amp, Codex, or any other executable that implements ACP over standard input and output.
|
|
7
|
+
ACP is useful for coding agents such as Claude Code, Cline, OpenCode, Amp, Codex, or any other executable that implements ACP over standard input and output.
|
|
8
8
|
|
|
9
9
|
## When to use ACP
|
|
10
10
|
|
|
@@ -30,6 +30,18 @@ The flow is:
|
|
|
30
30
|
|
|
31
31
|
During execution, the ACP client also handles permission requests and file operations. File reads and writes go through Mastra's `Workspace`, so the ACP agent operates inside the workspace you provide.
|
|
32
32
|
|
|
33
|
+
## Compatible agents
|
|
34
|
+
|
|
35
|
+
Any executable that implements ACP over standard input and output works with `@mastra/acp`. You don't need a dedicated Mastra package for each agent. Install the agent, then pass its launch command through `command` and `args`.
|
|
36
|
+
|
|
37
|
+
| Agent | `command` | `args` |
|
|
38
|
+
| ---------- | ---------- | ----------- |
|
|
39
|
+
| Cline | `cline` | `['--acp']` |
|
|
40
|
+
| OpenCode | `opencode` | `['acp']` |
|
|
41
|
+
| Gemini CLI | `gemini` | `['--acp']` |
|
|
42
|
+
|
|
43
|
+
Each agent documents its own ACP mode, and launch flags change between releases. Check the agent's documentation for the current command, such as [Cline ACP](https://docs.cline.bot/usage/acp) or [OpenCode ACP](https://opencode.ai/docs/acp/).
|
|
44
|
+
|
|
33
45
|
## Getting started
|
|
34
46
|
|
|
35
47
|
Install `@mastra/acp` in a project that already uses `@mastra/core`. The package requires `@mastra/core` version `1.34.0` or later.
|
|
@@ -75,8 +87,8 @@ const codeAgent = new AcpAgent({
|
|
|
75
87
|
id: 'code-agent',
|
|
76
88
|
name: 'Code Agent',
|
|
77
89
|
description: 'An ACP-compatible coding agent that can inspect and edit files',
|
|
78
|
-
command: '
|
|
79
|
-
args: ['
|
|
90
|
+
command: 'opencode',
|
|
91
|
+
args: ['acp'],
|
|
80
92
|
cwd: process.cwd(),
|
|
81
93
|
})
|
|
82
94
|
|
|
@@ -104,8 +116,8 @@ import { Agent } from '@mastra/core/agent'
|
|
|
104
116
|
const codeAgentTool = createACPTool({
|
|
105
117
|
id: 'code-agent',
|
|
106
118
|
description: 'Use an ACP-compatible coding agent to inspect and edit code',
|
|
107
|
-
command: '
|
|
108
|
-
args: ['
|
|
119
|
+
command: 'opencode',
|
|
120
|
+
args: ['acp'],
|
|
109
121
|
cwd: process.cwd(),
|
|
110
122
|
})
|
|
111
123
|
|
|
@@ -6,7 +6,7 @@ Connections let Mastra work with remote agents, coding agents, provider software
|
|
|
6
6
|
|
|
7
7
|
- [**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.
|
|
8
8
|
- [**Agent-to-Agent (A2A)**](https://mastra.ai/docs/connections/a2a): Expose or consume remote agents across service, framework, vendor, and language boundaries.
|
|
9
|
-
- [**Agent Client Protocol (ACP)**](https://mastra.ai/docs/connections/acp): Run compatible coding-agent processes as Mastra tools or subagents.
|
|
9
|
+
- [**Agent Client Protocol (ACP)**](https://mastra.ai/docs/connections/acp): Run compatible coding-agent processes, such as Claude Code, Cline, or OpenCode, as Mastra tools or subagents.
|
|
10
10
|
- [**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.
|
|
11
11
|
|
|
12
12
|
## When to use connections
|
|
@@ -17,6 +17,8 @@ SDK agents let you use other agent SDK frameworks inside Mastra. Use them to reg
|
|
|
17
17
|
- [Cursor Agent SDK](#cursor-agent-sdk): Use `@mastra/cursor` to register a Cursor SDK agent and call it with Mastra `generate()` and `stream()`.
|
|
18
18
|
- [OpenAI Agents SDK](#openai-agents-sdk): Use `@mastra/openai` to register an OpenAI SDK agent and call it with Mastra `generate()` and `stream()`.
|
|
19
19
|
|
|
20
|
+
Coding agents without a dedicated Mastra package, such as Cline and OpenCode, run through the [Agent Client Protocol](https://mastra.ai/docs/connections/acp) instead.
|
|
21
|
+
|
|
20
22
|
## Claude Agent SDK
|
|
21
23
|
|
|
22
24
|
Use `@mastra/claude` for Claude Code runtime configuration, permissions, tools, and agent-loop behavior.
|
|
@@ -118,6 +118,22 @@ const agent = new Agent({
|
|
|
118
118
|
export const eventedWriter = createEventedAgent({ agent })
|
|
119
119
|
```
|
|
120
120
|
|
|
121
|
+
### Stored agents created through the API
|
|
122
|
+
|
|
123
|
+
Agents created with [`createStoredAgent()`](https://mastra.ai/reference/client-js/agents) opt in with a `durable` field on the agent config. The server wraps the agent with `createDurableAgent()` when it hydrates it, so no code deployment is needed:
|
|
124
|
+
|
|
125
|
+
```typescript
|
|
126
|
+
await mastraClient.createStoredAgent({
|
|
127
|
+
id: 'helper',
|
|
128
|
+
name: 'Helper',
|
|
129
|
+
instructions: 'You are a helpful assistant.',
|
|
130
|
+
model: { provider: 'openai', name: 'gpt-5' },
|
|
131
|
+
durable: true,
|
|
132
|
+
})
|
|
133
|
+
```
|
|
134
|
+
|
|
135
|
+
`durable` also accepts `{ maxSteps, cleanupTimeoutMs }`. Cache and pubsub are inherited from the server's `Mastra` instance, so configure distributed backends there if you need durability across replicas. Automatic recovery is still configured in code through `recovery.durableAgents`.
|
|
136
|
+
|
|
121
137
|
### Inngest-powered with `createInngestAgent()`
|
|
122
138
|
|
|
123
139
|
Run the workflow on the [Inngest](https://www.inngest.com/docs) platform. Each tool call becomes a memoized step that Inngest can retry independently, and you get a dashboard for monitoring runs:
|
|
@@ -79,6 +79,7 @@ List of required environment variables for each model provider and gateway suppo
|
|
|
79
79
|
| [Kenari](https://mastra.ai/models/providers/kenari) | `kenari/*` | `KENARI_API_KEY` |
|
|
80
80
|
| [Kilo Gateway](https://mastra.ai/models/providers/kilo) | `kilo/*` | `KILO_API_KEY` |
|
|
81
81
|
| [Kimi For Coding](https://mastra.ai/models/providers/kimi-for-coding) | `kimi-for-coding/*` | `KIMI_API_KEY` |
|
|
82
|
+
| [Kosmik Compute](https://mastra.ai/models/providers/kosmik) | `kosmik/*` | `KOSMIK_API_KEY` |
|
|
82
83
|
| [KUAE Cloud Coding Plan](https://mastra.ai/models/providers/kuae-cloud-coding-plan) | `kuae-cloud-coding-plan/*` | `KUAE_API_KEY` |
|
|
83
84
|
| [Lilac](https://mastra.ai/models/providers/lilac) | `lilac/*` | `LILAC_API_KEY` |
|
|
84
85
|
| [Llama](https://mastra.ai/models/providers/llama) | `llama/*` | `LLAMA_API_KEY` |
|
|
@@ -2,7 +2,7 @@
|
|
|
2
2
|
|
|
3
3
|
# OpenRouter
|
|
4
4
|
|
|
5
|
-
OpenRouter aggregates models from multiple providers with enhanced features like rate limiting and failover. Access
|
|
5
|
+
OpenRouter aggregates models from multiple providers with enhanced features like rate limiting and failover. Access 350 models through Mastra's model router.
|
|
6
6
|
|
|
7
7
|
Learn more in the [OpenRouter documentation](https://openrouter.ai/models).
|
|
8
8
|
|
|
@@ -149,7 +149,6 @@ ANTHROPIC_API_KEY=ant-...
|
|
|
149
149
|
| `kwaipilot/kat-coder-air-v2.5` |
|
|
150
150
|
| `kwaipilot/kat-coder-pro-v2` |
|
|
151
151
|
| `kwaipilot/kat-coder-pro-v2.5` |
|
|
152
|
-
| `liquid/lfm-2.5-2.6b:free` |
|
|
153
152
|
| `mancer/weaver` |
|
|
154
153
|
| `meituan/longcat-2.0` |
|
|
155
154
|
| `meta-llama/llama-3.1-70b-instruct` |
|
|
@@ -386,5 +385,4 @@ ANTHROPIC_API_KEY=ant-...
|
|
|
386
385
|
| `z-ai/glm-5-turbo` |
|
|
387
386
|
| `z-ai/glm-5.1` |
|
|
388
387
|
| `z-ai/glm-5.2` |
|
|
389
|
-
| `z-ai/glm-5.2:free` |
|
|
390
388
|
| `z-ai/glm-5v-turbo` |
|
|
@@ -2,7 +2,7 @@
|
|
|
2
2
|
|
|
3
3
|
# Vercel
|
|
4
4
|
|
|
5
|
-
Vercel aggregates models from multiple providers with enhanced features like rate limiting and failover. Access
|
|
5
|
+
Vercel aggregates models from multiple providers with enhanced features like rate limiting and failover. Access 347 models through Mastra's model router.
|
|
6
6
|
|
|
7
7
|
Learn more in the [Vercel documentation](https://ai-sdk.dev/providers/ai-sdk-providers).
|
|
8
8
|
|
|
@@ -238,35 +238,51 @@ ANTHROPIC_API_KEY=ant-...
|
|
|
238
238
|
| `openai/gpt-3.5-turbo` |
|
|
239
239
|
| `openai/gpt-4-turbo` |
|
|
240
240
|
| `openai/gpt-4.1` |
|
|
241
|
+
| `openai/gpt-4.1-fast` |
|
|
241
242
|
| `openai/gpt-4.1-mini` |
|
|
243
|
+
| `openai/gpt-4.1-mini-fast` |
|
|
242
244
|
| `openai/gpt-4.1-nano` |
|
|
245
|
+
| `openai/gpt-4.1-nano-fast` |
|
|
243
246
|
| `openai/gpt-4o` |
|
|
247
|
+
| `openai/gpt-4o-fast` |
|
|
244
248
|
| `openai/gpt-4o-mini` |
|
|
249
|
+
| `openai/gpt-4o-mini-fast` |
|
|
245
250
|
| `openai/gpt-4o-mini-search-preview` |
|
|
246
251
|
| `openai/gpt-4o-mini-transcribe` |
|
|
247
252
|
| `openai/gpt-4o-transcribe` |
|
|
248
253
|
| `openai/gpt-5` |
|
|
249
254
|
| `openai/gpt-5-codex` |
|
|
255
|
+
| `openai/gpt-5-fast` |
|
|
250
256
|
| `openai/gpt-5-mini` |
|
|
257
|
+
| `openai/gpt-5-mini-fast` |
|
|
251
258
|
| `openai/gpt-5-nano` |
|
|
252
259
|
| `openai/gpt-5-pro` |
|
|
253
260
|
| `openai/gpt-5.1-codex` |
|
|
254
261
|
| `openai/gpt-5.1-codex-max` |
|
|
255
262
|
| `openai/gpt-5.1-codex-mini` |
|
|
256
263
|
| `openai/gpt-5.1-thinking` |
|
|
264
|
+
| `openai/gpt-5.1-thinking-fast` |
|
|
257
265
|
| `openai/gpt-5.2` |
|
|
258
266
|
| `openai/gpt-5.2-codex` |
|
|
267
|
+
| `openai/gpt-5.2-fast` |
|
|
259
268
|
| `openai/gpt-5.2-pro` |
|
|
260
269
|
| `openai/gpt-5.3-codex` |
|
|
270
|
+
| `openai/gpt-5.3-codex-fast` |
|
|
261
271
|
| `openai/gpt-5.4` |
|
|
272
|
+
| `openai/gpt-5.4-fast` |
|
|
262
273
|
| `openai/gpt-5.4-mini` |
|
|
274
|
+
| `openai/gpt-5.4-mini-fast` |
|
|
263
275
|
| `openai/gpt-5.4-nano` |
|
|
264
276
|
| `openai/gpt-5.4-pro` |
|
|
265
277
|
| `openai/gpt-5.5` |
|
|
278
|
+
| `openai/gpt-5.5-fast` |
|
|
266
279
|
| `openai/gpt-5.5-pro` |
|
|
267
280
|
| `openai/gpt-5.6-luna` |
|
|
281
|
+
| `openai/gpt-5.6-luna-fast` |
|
|
268
282
|
| `openai/gpt-5.6-sol` |
|
|
283
|
+
| `openai/gpt-5.6-sol-fast` |
|
|
269
284
|
| `openai/gpt-5.6-terra` |
|
|
285
|
+
| `openai/gpt-5.6-terra-fast` |
|
|
270
286
|
| `openai/gpt-image-1` |
|
|
271
287
|
| `openai/gpt-image-1-mini` |
|
|
272
288
|
| `openai/gpt-image-1.5` |
|
|
@@ -282,9 +298,11 @@ ANTHROPIC_API_KEY=ant-...
|
|
|
282
298
|
| `openai/o1` |
|
|
283
299
|
| `openai/o3` |
|
|
284
300
|
| `openai/o3-deep-research` |
|
|
301
|
+
| `openai/o3-fast` |
|
|
285
302
|
| `openai/o3-mini` |
|
|
286
303
|
| `openai/o3-pro` |
|
|
287
304
|
| `openai/o4-mini` |
|
|
305
|
+
| `openai/o4-mini-fast` |
|
|
288
306
|
| `openai/text-embedding-3-large` |
|
|
289
307
|
| `openai/text-embedding-3-small` |
|
|
290
308
|
| `openai/text-embedding-ada-002` |
|
package/.docs/models/index.md
CHANGED
|
@@ -2,7 +2,7 @@
|
|
|
2
2
|
|
|
3
3
|
# Model Providers
|
|
4
4
|
|
|
5
|
-
Mastra provides a unified interface for working with LLMs across multiple providers, giving you access to
|
|
5
|
+
Mastra provides a unified interface for working with LLMs across multiple providers, giving you access to 6097 models from 178 providers through a single API.
|
|
6
6
|
|
|
7
7
|
## Features
|
|
8
8
|
|
|
@@ -2,7 +2,7 @@
|
|
|
2
2
|
|
|
3
3
|
# Cloudflare Workers AI
|
|
4
4
|
|
|
5
|
-
Access
|
|
5
|
+
Access 25 Cloudflare Workers AI models through Mastra's model router. Authentication is handled automatically using the `CLOUDFLARE_API_KEY` environment variable. Configure `CLOUDFLARE_ACCOUNT_ID` as well.
|
|
6
6
|
|
|
7
7
|
Learn more in the [Cloudflare Workers AI documentation](https://developers.cloudflare.com/workers-ai/models/).
|
|
8
8
|
|
|
@@ -58,6 +58,7 @@ for await (const chunk of stream) {
|
|
|
58
58
|
| `cloudflare-workers-ai/@cf/openai/gpt-oss-20b` | 128K | | | | | | $0.20 | $0.30 |
|
|
59
59
|
| `cloudflare-workers-ai/@cf/qwen/qwen2.5-coder-32b-instruct` | 33K | | | | | | $0.66 | $1 |
|
|
60
60
|
| `cloudflare-workers-ai/@cf/qwen/qwen3-30b-a3b-fp8` | 33K | | | | | | $0.05 | $0.34 |
|
|
61
|
+
| `cloudflare-workers-ai/@cf/qwen/qwen3.8-27b` | 262K | | | | | | $0.45 | $3 |
|
|
61
62
|
| `cloudflare-workers-ai/@cf/qwen/qwq-32b` | 24K | | | | | | $0.66 | $1 |
|
|
62
63
|
| `cloudflare-workers-ai/@cf/zai-org/glm-4.7-flash` | 131K | | | | | | $0.06 | $0.40 |
|
|
63
64
|
| `cloudflare-workers-ai/@cf/zai-org/glm-5.2` | 262K | | | | | | $1 | $4 |
|
|
@@ -2,7 +2,7 @@
|
|
|
2
2
|
|
|
3
3
|
# Deep Infra
|
|
4
4
|
|
|
5
|
-
Access
|
|
5
|
+
Access 60 Deep Infra models through Mastra's model router. Authentication is handled automatically using the `DEEPINFRA_API_KEY` environment variable.
|
|
6
6
|
|
|
7
7
|
Learn more in the [Deep Infra documentation](https://deepinfra.com/models).
|
|
8
8
|
|
|
@@ -77,6 +77,7 @@ for await (const chunk of stream) {
|
|
|
77
77
|
| `deepinfra/Qwen/Qwen3.6-35B-A3B` | 262K | | | | | | $0.10 | $0.95 |
|
|
78
78
|
| `deepinfra/Qwen/Qwen3.7-Max` | 256K | | | | | | $3 | $8 |
|
|
79
79
|
| `deepinfra/Qwen/Qwen3.8-2.4T-A95B` | 262K | | | | | | $2 | $6 |
|
|
80
|
+
| `deepinfra/Qwen/Qwen3.8-27B` | 262K | | | | | | $0.40 | $3 |
|
|
80
81
|
| `deepinfra/Qwen/Qwen3.8-Max` | 256K | | | | | | $2 | $5 |
|
|
81
82
|
| `deepinfra/stepfun-ai/Step-3.7-Flash` | 262K | | | | | | $0.20 | $1 |
|
|
82
83
|
| `deepinfra/tencent/Hy3` | 262K | | | | | | $0.14 | $0.58 |
|
|
@@ -2,7 +2,7 @@
|
|
|
2
2
|
|
|
3
3
|
# Eden AI
|
|
4
4
|
|
|
5
|
-
Access
|
|
5
|
+
Access 234 Eden AI models through Mastra's model router. Authentication is handled automatically using the `EDENAI_API_KEY` environment variable.
|
|
6
6
|
|
|
7
7
|
Learn more in the [Eden AI documentation](https://docs.edenai.co).
|
|
8
8
|
|
|
@@ -66,6 +66,7 @@ for await (const chunk of stream) {
|
|
|
66
66
|
| `edenai/cloudflare/@cf/openai/gpt-oss-120b` | 128K | | | | | | $0.35 | $0.75 |
|
|
67
67
|
| `edenai/cloudflare/@cf/openai/gpt-oss-20b` | 128K | | | | | | $0.20 | $0.30 |
|
|
68
68
|
| `edenai/cloudflare/@cf/qwen/qwen2.5-coder-32b-instruct` | 33K | | | | | | $0.66 | $1 |
|
|
69
|
+
| `edenai/cloudflare/@cf/qwen/qwen3.8-27b` | 262K | | | | | | $0.45 | $3 |
|
|
69
70
|
| `edenai/cloudflare/@cf/zai-org/glm-4.7-flash` | 131K | | | | | | $0.06 | $0.40 |
|
|
70
71
|
| `edenai/cohere/command-a-03-2025` | 288K | | | | | | $3 | $10 |
|
|
71
72
|
| `edenai/cohere/command-r-08-2024` | 128K | | | | | | $0.15 | $0.60 |
|
|
@@ -90,6 +91,7 @@ for await (const chunk of stream) {
|
|
|
90
91
|
| `edenai/deepinfra/nvidia/Nemotron-3-Nano-30B-A3B` | 262K | | | | | | $0.05 | $0.20 |
|
|
91
92
|
| `edenai/deepinfra/openai/gpt-oss-120b` | 131K | | | | | | $0.04 | $0.17 |
|
|
92
93
|
| `edenai/deepinfra/openai/gpt-oss-20b` | 131K | | | | | | $0.03 | $0.14 |
|
|
94
|
+
| `edenai/deepinfra/Qwen/Qwen3.8-27B` | 262K | | | | | | $0.40 | $3 |
|
|
93
95
|
| `edenai/deepinfra/stepfun-ai/Step-3.5-Flash` | 262K | | | | | | $0.09 | $0.30 |
|
|
94
96
|
| `edenai/deepinfra/stepfun-ai/Step-3.7-Flash` | 262K | | | | | | $0.20 | $1 |
|
|
95
97
|
| `edenai/deepinfra/tencent/Hy3` | 262K | | | | | | $0.14 | $0.58 |
|
|
@@ -2,7 +2,7 @@
|
|
|
2
2
|
|
|
3
3
|
# Kilo Gateway
|
|
4
4
|
|
|
5
|
-
Access
|
|
5
|
+
Access 358 Kilo Gateway models through Mastra's model router. Authentication is handled automatically using the `KILO_API_KEY` environment variable.
|
|
6
6
|
|
|
7
7
|
Learn more in the [Kilo Gateway documentation](https://kilo.ai).
|
|
8
8
|
|
|
@@ -40,7 +40,7 @@ for await (const chunk of stream) {
|
|
|
40
40
|
| `kilo/~anthropic/claude-haiku-latest` | 200K | | | | | | $1 | $5 |
|
|
41
41
|
| `kilo/~anthropic/claude-opus-latest` | 1.0M | | | | | | $5 | $25 |
|
|
42
42
|
| `kilo/~anthropic/claude-sonnet-latest` | 1.0M | | | | | | $2 | $10 |
|
|
43
|
-
| `kilo/~deepseek/deepseek-v4-flash-latest` |
|
|
43
|
+
| `kilo/~deepseek/deepseek-v4-flash-latest` | 1.0M | | | | | | $0.08 | $0.16 |
|
|
44
44
|
| `kilo/~google/gemini-flash-latest` | 1.0M | | | | | | $0.38 | $2 |
|
|
45
45
|
| `kilo/~google/gemini-pro-latest` | 1.0M | | | | | | $2 | $12 |
|
|
46
46
|
| `kilo/~moonshotai/kimi-latest` | 975K | | | | | | $3 | $13 |
|
|
@@ -154,7 +154,6 @@ for await (const chunk of stream) {
|
|
|
154
154
|
| `kilo/kwaipilot/kat-coder-air-v2.5` | 256K | | | | | | $0.15 | $0.60 |
|
|
155
155
|
| `kilo/kwaipilot/kat-coder-pro-v2` | 256K | | | | | | $0.30 | $1 |
|
|
156
156
|
| `kilo/kwaipilot/kat-coder-pro-v2.5` | 256K | | | | | | $0.74 | $3 |
|
|
157
|
-
| `kilo/liquid/lfm-2.5-2.6b:free` | 128K | | | | | | — | — |
|
|
158
157
|
| `kilo/mancer/weaver` | 8K | | | | | | $0.50 | $0.75 |
|
|
159
158
|
| `kilo/meituan/longcat-2.0` | 1.0M | | | | | | $0.75 | $3 |
|
|
160
159
|
| `kilo/meta-llama/llama-3.1-70b-instruct` | 131K | | | | | | $0.40 | $0.40 |
|
|
@@ -394,7 +393,6 @@ for await (const chunk of stream) {
|
|
|
394
393
|
| `kilo/z-ai/glm-5-turbo` | 203K | | | | | | $1 | $4 |
|
|
395
394
|
| `kilo/z-ai/glm-5.1` | 200K | | | | | | $1 | $4 |
|
|
396
395
|
| `kilo/z-ai/glm-5.2` | 1.0M | | | | | | $1 | $4 |
|
|
397
|
-
| `kilo/z-ai/glm-5.2:free` | 128K | | | | | | — | — |
|
|
398
396
|
| `kilo/z-ai/glm-5v-turbo` | 203K | | | | | | $1 | $4 |
|
|
399
397
|
|
|
400
398
|
## Advanced configuration
|
|
@@ -0,0 +1,73 @@
|
|
|
1
|
+
> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
|
|
2
|
+
|
|
3
|
+
# Kosmik Compute
|
|
4
|
+
|
|
5
|
+
Access 1 Kosmik Compute model through Mastra's model router. Authentication is handled automatically using the `KOSMIK_API_KEY` environment variable.
|
|
6
|
+
|
|
7
|
+
Learn more in the [Kosmik Compute documentation](https://api.koscompute.com/docs/).
|
|
8
|
+
|
|
9
|
+
```bash
|
|
10
|
+
KOSMIK_API_KEY=your-api-key
|
|
11
|
+
```
|
|
12
|
+
|
|
13
|
+
```typescript
|
|
14
|
+
import { Agent } from "@mastra/core/agent";
|
|
15
|
+
|
|
16
|
+
const agent = new Agent({
|
|
17
|
+
id: "my-agent",
|
|
18
|
+
name: "My Agent",
|
|
19
|
+
instructions: "You are a helpful assistant",
|
|
20
|
+
model: "kosmik/qwen/qwen3.8-27b"
|
|
21
|
+
});
|
|
22
|
+
|
|
23
|
+
// Generate a response
|
|
24
|
+
const response = await agent.generate("Hello!");
|
|
25
|
+
|
|
26
|
+
// Stream a response
|
|
27
|
+
const stream = await agent.stream("Tell me a story");
|
|
28
|
+
for await (const chunk of stream) {
|
|
29
|
+
console.log(chunk);
|
|
30
|
+
}
|
|
31
|
+
```
|
|
32
|
+
|
|
33
|
+
> **Note:** Mastra uses the OpenAI-compatible `/chat/completions` endpoint. Some provider-specific features may not be available. Check the [Kosmik Compute documentation](https://api.koscompute.com/docs/) for details.
|
|
34
|
+
|
|
35
|
+
## Models
|
|
36
|
+
|
|
37
|
+
| Model | Context | Tools | Reasoning | Image | Audio | Video | Input $/1M | Output $/1M |
|
|
38
|
+
| ------------------------- | ------- | ----- | --------- | ----- | ----- | ----- | ---------- | ----------- |
|
|
39
|
+
| `kosmik/qwen/qwen3.8-27b` | 262K | | | | | | $0.35 | $2 |
|
|
40
|
+
|
|
41
|
+
## Advanced configuration
|
|
42
|
+
|
|
43
|
+
### Custom headers
|
|
44
|
+
|
|
45
|
+
```typescript
|
|
46
|
+
const agent = new Agent({
|
|
47
|
+
id: "custom-agent",
|
|
48
|
+
name: "custom-agent",
|
|
49
|
+
model: {
|
|
50
|
+
url: "https://api.koscompute.com/v1",
|
|
51
|
+
id: "kosmik/qwen/qwen3.8-27b",
|
|
52
|
+
apiKey: process.env.KOSMIK_API_KEY,
|
|
53
|
+
headers: {
|
|
54
|
+
"X-Custom-Header": "value"
|
|
55
|
+
}
|
|
56
|
+
}
|
|
57
|
+
});
|
|
58
|
+
```
|
|
59
|
+
|
|
60
|
+
### Dynamic model selection
|
|
61
|
+
|
|
62
|
+
```typescript
|
|
63
|
+
const agent = new Agent({
|
|
64
|
+
id: "dynamic-agent",
|
|
65
|
+
name: "Dynamic Agent",
|
|
66
|
+
model: ({ requestContext }) => {
|
|
67
|
+
const useAdvanced = requestContext.task === "complex";
|
|
68
|
+
return useAdvanced
|
|
69
|
+
? "kosmik/qwen/qwen3.8-27b"
|
|
70
|
+
: "kosmik/qwen/qwen3.8-27b";
|
|
71
|
+
}
|
|
72
|
+
});
|
|
73
|
+
```
|
|
@@ -2,7 +2,7 @@
|
|
|
2
2
|
|
|
3
3
|
# Merge Gateway
|
|
4
4
|
|
|
5
|
-
Access
|
|
5
|
+
Access 172 Merge Gateway models through Mastra's model router. Authentication is handled automatically using the `MERGE_GATEWAY_API_KEY` environment variable.
|
|
6
6
|
|
|
7
7
|
Learn more in the [Merge Gateway documentation](https://docs.merge.dev/merge-gateway).
|
|
8
8
|
|
|
@@ -183,6 +183,7 @@ for await (const chunk of stream) {
|
|
|
183
183
|
| `merge-gateway/qwen/qwen3.7-plus` | 1.0M | | | | | | $0.40 | $2 |
|
|
184
184
|
| `merge-gateway/qwen/qwen3.8-max` | 1.0M | | | | | | $2 | $6 |
|
|
185
185
|
| `merge-gateway/sakana/fugu-ultra` | 1.0M | | | | | | $5 | $30 |
|
|
186
|
+
| `merge-gateway/sakana/sakana-namazu` | 262K | | | | | | $0.95 | $4 |
|
|
186
187
|
| `merge-gateway/thinkingmachines/inkling` | 1.0M | | | | | | $1 | $4 |
|
|
187
188
|
| `merge-gateway/writer/palmyra-x4` | 128K | | | | | | $3 | $10 |
|
|
188
189
|
| `merge-gateway/writer/palmyra-x5` | 1.0M | | | | | | $0.60 | $6 |
|
|
@@ -401,12 +401,12 @@ for await (const chunk of stream) {
|
|
|
401
401
|
| `nano-gpt/openai/gpt-5.5` | 1.0M | | | | | | $5 | $30 |
|
|
402
402
|
| `nano-gpt/openai/gpt-5.6-luna` | 1.1M | | | | | | $0.10 | $0.60 |
|
|
403
403
|
| `nano-gpt/openai/gpt-5.6-luna-pro` | 1.1M | | | | | | $0.10 | $0.60 |
|
|
404
|
-
| `nano-gpt/openai/gpt-5.6-sol` | 1.1M | | | | | | $
|
|
405
|
-
| `nano-gpt/openai/gpt-5.6-sol-pro` | 1.1M | | | | | | $
|
|
404
|
+
| `nano-gpt/openai/gpt-5.6-sol` | 1.1M | | | | | | $3 | $15 |
|
|
405
|
+
| `nano-gpt/openai/gpt-5.6-sol-pro` | 1.1M | | | | | | $3 | $15 |
|
|
406
406
|
| `nano-gpt/openai/gpt-5.6-terra` | 1.1M | | | | | | $1 | $6 |
|
|
407
407
|
| `nano-gpt/openai/gpt-5.6-terra-pro` | 1.1M | | | | | | $1 | $6 |
|
|
408
|
-
| `nano-gpt/openai/gpt-chat-latest` | 1.1M | | | | | | $
|
|
409
|
-
| `nano-gpt/openai/gpt-latest` | 1.1M | | | | | | $
|
|
408
|
+
| `nano-gpt/openai/gpt-chat-latest` | 1.1M | | | | | | $3 | $15 |
|
|
409
|
+
| `nano-gpt/openai/gpt-latest` | 1.1M | | | | | | $3 | $15 |
|
|
410
410
|
| `nano-gpt/openai/gpt-oss-120b` | 128K | | | | | | $0.35 | $0.75 |
|
|
411
411
|
| `nano-gpt/openai/gpt-oss-20b` | 128K | | | | | | $0.20 | $0.30 |
|
|
412
412
|
| `nano-gpt/openai/gpt-oss-safeguard-20b` | 128K | | | | | | $0.07 | $0.30 |
|
|
@@ -2,7 +2,7 @@
|
|
|
2
2
|
|
|
3
3
|
# Sakana AI
|
|
4
4
|
|
|
5
|
-
Access
|
|
5
|
+
Access 4 Sakana AI models through Mastra's model router. Authentication is handled automatically using the `SAKANA_API_KEY` environment variable.
|
|
6
6
|
|
|
7
7
|
Learn more in the [Sakana AI documentation](https://console.sakana.ai/models).
|
|
8
8
|
|
|
@@ -39,6 +39,7 @@ for await (const chunk of stream) {
|
|
|
39
39
|
| `sakana/fugu` | 1.0M | | | | | | — | — |
|
|
40
40
|
| `sakana/fugu-ultra` | 1.0M | | | | | | $5 | $30 |
|
|
41
41
|
| `sakana/fugu-ultra-20260615` | 1.0M | | | | | | $5 | $30 |
|
|
42
|
+
| `sakana/sakana-namazu` | 262K | | | | | | $0.95 | $4 |
|
|
42
43
|
|
|
43
44
|
## Advanced configuration
|
|
44
45
|
|
|
@@ -68,7 +69,7 @@ const agent = new Agent({
|
|
|
68
69
|
model: ({ requestContext }) => {
|
|
69
70
|
const useAdvanced = requestContext.task === "complex";
|
|
70
71
|
return useAdvanced
|
|
71
|
-
? "sakana/
|
|
72
|
+
? "sakana/sakana-namazu"
|
|
72
73
|
: "sakana/fugu";
|
|
73
74
|
}
|
|
74
75
|
});
|
|
@@ -80,6 +80,7 @@ Direct access to individual AI model providers. Each provider offers unique mode
|
|
|
80
80
|
- [Kenari](https://mastra.ai/models/providers/kenari)
|
|
81
81
|
- [Kilo Gateway](https://mastra.ai/models/providers/kilo)
|
|
82
82
|
- [Kimi For Coding](https://mastra.ai/models/providers/kimi-for-coding)
|
|
83
|
+
- [Kosmik Compute](https://mastra.ai/models/providers/kosmik)
|
|
83
84
|
- [KUAE Cloud Coding Plan](https://mastra.ai/models/providers/kuae-cloud-coding-plan)
|
|
84
85
|
- [Lilac](https://mastra.ai/models/providers/lilac)
|
|
85
86
|
- [Llama](https://mastra.ai/models/providers/llama)
|
|
@@ -164,6 +164,8 @@ const result = await agent.generate('message for agent')
|
|
|
164
164
|
|
|
165
165
|
**options.modelSettings.frequencyPenalty** (`number`): Penalty for token frequency (-2 to 2). Reduces repetition of frequent tokens.
|
|
166
166
|
|
|
167
|
+
**options.modelSettings.timeout** (`object`): Time-based execution budget for the run. Accepts totalMs, the maximum duration of the entire agent run across every loop iteration, tool call and retry, and stepMs, the maximum duration of a single model call including the time spent consuming its stream. Exceeding either budget fails with a MastraTimeoutError. A totalMs timeout ends the run and does not try fallback models, because it is a hard deadline for the whole run. A stepMs timeout is not retried against the same model but does advance to the next entry in models when fallback models are configured.
|
|
168
|
+
|
|
167
169
|
**options.modelSettings.stopSequences** (`string[]`): Stop sequences. If set, the model will stop generating text when one of the stop sequences is generated.
|
|
168
170
|
|
|
169
171
|
**options.toolChoice** (`'auto' | 'none' | 'required' | { type: 'tool'; toolName: string }`): Controls how tools are selected during generation.
|
|
@@ -100,6 +100,8 @@ await agent.network(`
|
|
|
100
100
|
|
|
101
101
|
**options.modelSettings.frequencyPenalty** (`number`): Penalty for token frequency (-2 to 2). Reduces repetition of frequent tokens.
|
|
102
102
|
|
|
103
|
+
**options.modelSettings.timeout** (`object`): Time-based execution budget for the run. Accepts totalMs, the maximum duration of the entire agent run across every loop iteration, tool call and retry, and stepMs, the maximum duration of a single model call including the time spent consuming its stream. Exceeding either budget fails with a MastraTimeoutError. A totalMs timeout ends the run and does not try fallback models, because it is a hard deadline for the whole run. A stepMs timeout is not retried against the same model but does advance to the next entry in models when fallback models are configured.
|
|
104
|
+
|
|
103
105
|
**options.modelSettings.stopSequences** (`string[]`): Stop sequences. If set, the model will stop generating text when one of the stop sequences is generated.
|
|
104
106
|
|
|
105
107
|
**options.structuredOutput** (`StructuredOutputOptions`): Configuration for generating a typed structured output from the network result.
|
|
@@ -778,9 +778,29 @@ const agent = await mastraClient.createStoredAgent({
|
|
|
778
778
|
version: '1.0',
|
|
779
779
|
team: 'engineering',
|
|
780
780
|
},
|
|
781
|
+
durable: true,
|
|
781
782
|
})
|
|
782
783
|
```
|
|
783
784
|
|
|
785
|
+
#### Durable stored agents
|
|
786
|
+
|
|
787
|
+
Set `durable` to run the agent as a [durable agent](https://mastra.ai/docs/harness/durable-agents) once the server hydrates it. Pass `true` to accept the defaults, or an object to tune the durable loop:
|
|
788
|
+
|
|
789
|
+
```typescript
|
|
790
|
+
const agent = await mastraClient.createStoredAgent({
|
|
791
|
+
id: 'durable-agent',
|
|
792
|
+
name: 'Durable Agent',
|
|
793
|
+
instructions: 'You are a helpful assistant.',
|
|
794
|
+
model: {
|
|
795
|
+
provider: 'openai',
|
|
796
|
+
name: 'gpt-5.4',
|
|
797
|
+
},
|
|
798
|
+
durable: { maxSteps: 50, cleanupTimeoutMs: 0 },
|
|
799
|
+
})
|
|
800
|
+
```
|
|
801
|
+
|
|
802
|
+
Only serializable options are accepted. The durable cache and pubsub are inherited from the server's `Mastra` instance. If it has no distributed cache or pubsub configured, durability is process-local. Automatic recovery is still configured in code through `recovery.durableAgents`.
|
|
803
|
+
|
|
784
804
|
### `getStoredAgent()`
|
|
785
805
|
|
|
786
806
|
Get an instance of a specific stored agent:
|
|
@@ -64,6 +64,10 @@ for await (const part of stream.fullStream) {
|
|
|
64
64
|
}
|
|
65
65
|
```
|
|
66
66
|
|
|
67
|
+
## Media token counting
|
|
68
|
+
|
|
69
|
+
Images and file attachments are estimated rather than tokenized. This applies to `file` message parts and to tool results shaped like `{ data, mediaType }`. Images use a flat per-image estimate, other media is estimated from its decoded byte size, and remote URLs or provider file ids use a flat fallback because their size isn't known locally. Encoded payloads such as base64 data are never counted as text, which would otherwise inflate the count by an order of magnitude and truncate history unnecessarily.
|
|
70
|
+
|
|
67
71
|
## Error behavior
|
|
68
72
|
|
|
69
73
|
When used as an input processor (both `processInput` and `processInputStep`), `TokenLimiterProcessor` throws a `TripWire` error in the following cases:
|
|
@@ -158,6 +158,8 @@ const stream = await agent.stream('message for agent')
|
|
|
158
158
|
|
|
159
159
|
**options.modelSettings.frequencyPenalty** (`number`): Penalty for token frequency (-2 to 2). Reduces repetition of frequent tokens.
|
|
160
160
|
|
|
161
|
+
**options.modelSettings.timeout** (`object`): Time-based execution budget for the run. Accepts totalMs, the maximum duration of the entire agent run across every loop iteration, tool call and retry, and stepMs, the maximum duration of a single model call including the time spent consuming its stream. Exceeding either budget fails with a MastraTimeoutError. A totalMs timeout ends the run and does not try fallback models, because it is a hard deadline for the whole run. A stepMs timeout is not retried against the same model but does advance to the next entry in models when fallback models are configured.
|
|
162
|
+
|
|
161
163
|
**options.modelSettings.stopSequences** (`string[]`): Stop sequences. If set, the model will stop generating text when one of the stop sequences is generated.
|
|
162
164
|
|
|
163
165
|
**options.toolChoice** (`'auto' | 'none' | 'required' | { type: 'tool'; toolName: string }`): Controls how the agent uses tools during streaming.
|
|
@@ -264,6 +266,26 @@ for await (const chunk of stream.fullStream) {
|
|
|
264
266
|
const fullText = await stream.text
|
|
265
267
|
```
|
|
266
268
|
|
|
269
|
+
### Limiting execution time
|
|
270
|
+
|
|
271
|
+
Use `modelSettings.timeout` to bound how long a run may take. `totalMs` limits the entire run, including every loop iteration, tool call and retry. `stepMs` limits a single model call, covering both establishing the stream and consuming it.
|
|
272
|
+
|
|
273
|
+
```ts
|
|
274
|
+
const stream = await agent.stream('Tell me a story', {
|
|
275
|
+
modelSettings: {
|
|
276
|
+
timeout: {
|
|
277
|
+
totalMs: 30000, // fail the run if it takes longer than 30s
|
|
278
|
+
stepMs: 10000, // fail an individual model call after 10s
|
|
279
|
+
},
|
|
280
|
+
},
|
|
281
|
+
})
|
|
282
|
+
```
|
|
283
|
+
|
|
284
|
+
Exceeding either budget fails with a `MastraTimeoutError`, which carries a `timeoutType` of `'total'` or `'step'`. Each budget behaves differently when the agent is configured with fallback [`models`](https://mastra.ai/reference/agents/agent):
|
|
285
|
+
|
|
286
|
+
- A `totalMs` timeout ends the run immediately and doesn't try the next model, because it's a hard deadline for the run as a whole.
|
|
287
|
+
- A `stepMs` timeout isn't retried against the same model, but does advance to the next model, which makes it a way to fail over from a slow provider.
|
|
288
|
+
|
|
267
289
|
### AI SDK v5+ Format
|
|
268
290
|
|
|
269
291
|
To use the stream with AI SDK v5 (and later), you can convert it using our utility function `toAISdkStream`.
|
|
@@ -65,6 +65,8 @@ Each server in the `servers` map is configured using the `MastraMCPServerDefinit
|
|
|
65
65
|
|
|
66
66
|
**requireToolApproval** (`boolean | (params: RequireToolApprovalContext) => boolean | Promise<boolean>`): Require human approval before executing tools from this server. When set to true, all tools require approval. When set to a function, the function is called with the tool name, arguments, request context, and any tool annotations advertised by the server to dynamically decide whether approval is needed.
|
|
67
67
|
|
|
68
|
+
**protocolVersion** (`'auto' | '2026-07-28'`): Opt-in MCP protocol version negotiation. Omitted keeps the legacy (2025-era) connect sequence unchanged. 'auto' probes the server at connect time and uses the stateless '2026-07-28' revision when the server supports it, with a safe fallback to the legacy handshake. '2026-07-28' pins that revision exactly and fails with a typed error when the server does not offer it. Elicitation handlers work on both eras: on a '2026-07-28' connection, embedded elicitation requests from input\_required results are dispatched through the same registered handler and the originating call retries automatically.
|
|
69
|
+
|
|
68
70
|
## Tool approval
|
|
69
71
|
|
|
70
72
|
Use `requireToolApproval` on a server definition to require human approval before any tool from that server is executed. This works with the existing [human-in-the-loop](https://mastra.ai/docs/workflows/human-in-the-loop) approval flow.
|
|
@@ -91,6 +91,35 @@ The constructor accepts an `MCPServerConfig` object with the following propertie
|
|
|
91
91
|
|
|
92
92
|
**appResources** (`AppResources`): A map of ui:// URIs to app resource configurations. Each entry defines an interactive HTML UI served via the MCP Apps extension (SEP-1865). See the MCP Apps section for details.
|
|
93
93
|
|
|
94
|
+
**protocolVersion** (`'2025-11-25' | '2026-07-28'`): Opt-in MCP protocol revision. Omitted (or '2025-11-25') keeps the legacy behavior exactly. Set to '2026-07-28' to serve the stateless MCP revision. See the Protocol versions section for details.
|
|
95
|
+
|
|
96
|
+
**cacheHints** (`MCPServerCacheHints`): Cache hints (ttlMs / cacheScope) advertised on cacheable results of the '2026-07-28' protocol revision, keyed by operation (e.g. 'tools/list'). Only applied when protocolVersion: '2026-07-28' is set.
|
|
97
|
+
|
|
98
|
+
## Protocol versions
|
|
99
|
+
|
|
100
|
+
By default, `MCPServer` speaks the legacy (2025-era) MCP protocol: sessionful streamable HTTP with an `initialize` handshake. Set `protocolVersion: '2026-07-28'` to serve the stateless MCP revision instead:
|
|
101
|
+
|
|
102
|
+
- HTTP and serverless requests go through a dual-era handler: clients that speak `2026-07-28` are served natively (stateless, per-request envelope), and legacy clients are served through a built-in stateless fallback on the same endpoint.
|
|
103
|
+
- `startStdio()` serves both eras: the opening exchange selects the era for the connection.
|
|
104
|
+
- Tool list, prompt list, resource list, and resource update notifications also reach `2026-07-28` clients through `subscriptions/listen`.
|
|
105
|
+
- Tool log messages honor the caller's per-request `logLevel` opt-in instead of the session-level `logging/setLevel`.
|
|
106
|
+
- Configured `cacheHints` are advertised on cacheable results such as `tools/list`.
|
|
107
|
+
- Tool elicitation (`options.mcp.elicitation.sendRequest()`) works on both eras. On `2026-07-28` requests, it uses the protocol's multi round-trip mechanism. The tool call first returns an `input_required` result. After the client answers, the call retries with the answer attached. The `sendRequest()` promise API is unchanged, but the tool function re-executes from the top on each retry, so keep side effects idempotent (or place them after the last elicitation) and keep the order of `sendRequest()` calls deterministic for a given input.
|
|
108
|
+
|
|
109
|
+
```typescript
|
|
110
|
+
const server = new MCPServer({
|
|
111
|
+
name: 'My Server',
|
|
112
|
+
version: '1.0.0',
|
|
113
|
+
tools: { weatherTool },
|
|
114
|
+
protocolVersion: '2026-07-28',
|
|
115
|
+
cacheHints: {
|
|
116
|
+
'tools/list': { ttlMs: 60_000, cacheScope: 'private' },
|
|
117
|
+
},
|
|
118
|
+
})
|
|
119
|
+
```
|
|
120
|
+
|
|
121
|
+
Omitting `protocolVersion` keeps the current behavior unchanged.
|
|
122
|
+
|
|
94
123
|
## Exposing agents as tools
|
|
95
124
|
|
|
96
125
|
A powerful feature of `MCPServer` is its ability to automatically expose your Mastra Agents as callable tools. When you provide agents in the `agents` property of the configuration:
|
|
@@ -239,6 +268,8 @@ await server.startStdio()
|
|
|
239
268
|
|
|
240
269
|
### `startSSE()`
|
|
241
270
|
|
|
271
|
+
> **Warning:** The HTTP+SSE transport is deprecated in the MCP specification. Use `startHTTP()` (streamable HTTP) instead.
|
|
272
|
+
|
|
242
273
|
This method helps you integrate the MCP server with an existing web server to use Server-Sent Events (SSE) for communication. You'll call this from your web server's code when it receives a request for the SSE or message paths.
|
|
243
274
|
|
|
244
275
|
```typescript
|
|
@@ -291,6 +322,8 @@ Here are the details for the values needed by the `startSSE` method:
|
|
|
291
322
|
|
|
292
323
|
### `startHonoSSE()`
|
|
293
324
|
|
|
325
|
+
> **Warning:** The HTTP+SSE transport is deprecated in the MCP specification. Use `startHTTP()` (streamable HTTP) instead.
|
|
326
|
+
|
|
294
327
|
This method helps you integrate the MCP server with an existing web server to use Server-Sent Events (SSE) for communication. You'll call this from your web server's code when it receives a request for the SSE or message paths.
|
|
295
328
|
|
|
296
329
|
```typescript
|
|
@@ -361,6 +394,21 @@ async startHTTP({
|
|
|
361
394
|
}): Promise<void>
|
|
362
395
|
```
|
|
363
396
|
|
|
397
|
+
#### Options with `protocolVersion: '2026-07-28'`
|
|
398
|
+
|
|
399
|
+
The `2026-07-28` protocol uses one shared stateless handler instead of a transport configured for each request. `startHTTP()` handles legacy transport options as follows:
|
|
400
|
+
|
|
401
|
+
| Options | Behavior |
|
|
402
|
+
| ------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------- |
|
|
403
|
+
| `serverless: true`, `serverlessStreaming: true`, `sessionIdGenerator: undefined` | Accepted because the modern handler already provides stateless requests and automatic request-scoped streaming. |
|
|
404
|
+
| `allowedHosts`, `allowedOrigins`, `enableDnsRebindingProtection` | Enforced before the request reaches the modern handler. Host and origin lists are active when `enableDnsRebindingProtection` is `true`. |
|
|
405
|
+
| `sessionIdGenerator` with a function, session callbacks, or `eventStore` | Rejected because the modern protocol doesn't create HTTP sessions. |
|
|
406
|
+
| `enableJsonResponse`, `retryInterval`, `keepAliveMs`, or `supportedProtocolVersions` | Rejected because these values configure a shared handler and can't vary between requests. |
|
|
407
|
+
| `serverless: false` or `serverlessStreaming: false` | Rejected because these values request behavior that differs from the modern handler. |
|
|
408
|
+
| Unknown options | Rejected instead of being ignored. |
|
|
409
|
+
|
|
410
|
+
Omit `options` when you don't need request guards or compatibility declarations.
|
|
411
|
+
|
|
364
412
|
Here's an example of how you might use `startHTTP` within an HTTP server request handler. In this example an MCP client could connect to your MCP server at `http://localhost:1234/http`:
|
|
365
413
|
|
|
366
414
|
```typescript
|
|
@@ -383,7 +431,7 @@ httpServer.listen(PORT, () => {
|
|
|
383
431
|
})
|
|
384
432
|
```
|
|
385
433
|
|
|
386
|
-
For **serverless environments** (Supabase Edge Functions, Cloudflare Workers, Vercel Edge, etc.), use `serverless: true` to enable stateless operation:
|
|
434
|
+
For **serverless environments** (Supabase Edge Functions, Cloudflare Workers, Vercel Edge, etc.), use `serverless: true` to enable stateless operation on the legacy protocol path. Servers configured with `protocolVersion: '2026-07-28'` are already stateless and may omit this option.
|
|
387
435
|
|
|
388
436
|
```typescript
|
|
389
437
|
// Supabase Edge Function example
|
|
@@ -457,7 +505,7 @@ serve(async req => {
|
|
|
457
505
|
>
|
|
458
506
|
> This is still stateless: no `mcp-session-id` is required or persisted. It only enables notifications scoped to the current request (such as progress). The session-dependent features below remain unavailable.
|
|
459
507
|
>
|
|
460
|
-
>
|
|
508
|
+
> On the legacy protocol path, the following MCP features require session state or persistent connections and **won't work** in serverless mode (including with `serverlessStreaming: true`):
|
|
461
509
|
>
|
|
462
510
|
> - **Elicitation** - Interactive user input requests during tool execution require session management to route responses back to the correct client
|
|
463
511
|
> - **Resource subscriptions** - `resources/subscribe` and `resources/unsubscribe` need persistent connections to maintain subscription state
|
package/CHANGELOG.md
CHANGED
|
@@ -1,5 +1,20 @@
|
|
|
1
1
|
# @mastra/mcp-docs-server
|
|
2
2
|
|
|
3
|
+
## 1.2.17-alpha.18
|
|
4
|
+
|
|
5
|
+
### Patch Changes
|
|
6
|
+
|
|
7
|
+
- Updated dependencies [[`6223446`](https://github.com/mastra-ai/mastra/commit/6223446ddce6166e96e0ba5e00d628b615dee8ca), [`583e235`](https://github.com/mastra-ai/mastra/commit/583e23519c13af16c1746f9c49722d011216611b), [`a77f8d4`](https://github.com/mastra-ai/mastra/commit/a77f8d4740d2178a74c41e4bf678b4fcd8fa0bb2), [`40d358e`](https://github.com/mastra-ai/mastra/commit/40d358e29d55543803e64b49241122f598ffabc7), [`e80cd7e`](https://github.com/mastra-ai/mastra/commit/e80cd7e7683e7d732e1cc6784bcac1d2640d2ce3), [`39ba1b9`](https://github.com/mastra-ai/mastra/commit/39ba1b9ce256a9a910a16f125cc6a59588185bfe), [`0f53aeb`](https://github.com/mastra-ai/mastra/commit/0f53aeb119158bd9f83bd8ef667f1f675740e8f0), [`20504b2`](https://github.com/mastra-ai/mastra/commit/20504b2ecebd0e077acda3d457ab57480a98ed3e)]:
|
|
8
|
+
- @mastra/core@1.60.0-alpha.11
|
|
9
|
+
- @mastra/mcp@1.17.0-alpha.2
|
|
10
|
+
|
|
11
|
+
## 1.2.17-alpha.17
|
|
12
|
+
|
|
13
|
+
### Patch Changes
|
|
14
|
+
|
|
15
|
+
- Updated dependencies [[`b860493`](https://github.com/mastra-ai/mastra/commit/b86049391100e665d579f700c8a2034c036defc3)]:
|
|
16
|
+
- @mastra/core@1.60.0-alpha.10
|
|
17
|
+
|
|
3
18
|
## 1.2.17-alpha.15
|
|
4
19
|
|
|
5
20
|
### Patch Changes
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@mastra/mcp-docs-server",
|
|
3
|
-
"version": "1.2.17-alpha.
|
|
3
|
+
"version": "1.2.17-alpha.18",
|
|
4
4
|
"description": "MCP server for accessing Mastra.ai documentation, changelogs, and news.",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"main": "dist/index.js",
|
|
@@ -28,8 +28,8 @@
|
|
|
28
28
|
"jsdom": "^26.1.0",
|
|
29
29
|
"local-pkg": "^1.1.2",
|
|
30
30
|
"zod": "^4.4.3",
|
|
31
|
-
"@mastra/
|
|
32
|
-
"@mastra/
|
|
31
|
+
"@mastra/mcp": "^1.17.0-alpha.2",
|
|
32
|
+
"@mastra/core": "1.60.0-alpha.11"
|
|
33
33
|
},
|
|
34
34
|
"devDependencies": {
|
|
35
35
|
"@hono/node-server": "^2.0.0",
|
|
@@ -45,9 +45,9 @@
|
|
|
45
45
|
"tsx": "^4.23.1",
|
|
46
46
|
"typescript": "^6.0.3",
|
|
47
47
|
"vitest": "4.1.10",
|
|
48
|
-
"@
|
|
48
|
+
"@mastra/core": "1.60.0-alpha.11",
|
|
49
49
|
"@internal/types-builder": "0.0.98",
|
|
50
|
-
"@
|
|
50
|
+
"@internal/lint": "0.0.123"
|
|
51
51
|
},
|
|
52
52
|
"homepage": "https://mastra.ai",
|
|
53
53
|
"repository": {
|