@mastra/mcp-docs-server 1.1.23 → 1.1.24-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.
Files changed (14) hide show
  1. package/.docs/docs/editor/overview.md +66 -0
  2. package/.docs/docs/editor/prompts.md +63 -0
  3. package/.docs/docs/editor/tools.md +2 -2
  4. package/.docs/docs/observability/tracing/exporters/cloud.md +28 -2
  5. package/.docs/models/gateways/openrouter.md +4 -2
  6. package/.docs/models/index.md +1 -1
  7. package/.docs/models/providers/cortecs.md +2 -1
  8. package/.docs/models/providers/fireworks-ai.md +3 -1
  9. package/.docs/reference/core/getEditor.md +35 -0
  10. package/.docs/reference/editor/mastra-editor.md +79 -1
  11. package/.docs/reference/index.md +1 -0
  12. package/.docs/reference/observability/tracing/exporters/cloud-exporter.md +26 -2
  13. package/CHANGELOG.md +7 -0
  14. package/package.json +4 -4
package/.docs/docs/editor/overview.md CHANGED
@@ -72,6 +72,72 @@ Go to the **Agents** tab in Studio and select an agent to edit. Select the **Edi
72
72
 
73
73
  Modify the system prompt and save a new draft version. Afterwards, publish the draft to make it the active version.
74
74
 
75
+ ## Programmatic control
76
+
77
+ Everything you can do in Studio is also available programmatically through [`mastra.getEditor()`](https://mastra.ai/reference/core/getEditor). This is useful for scripting bulk updates, seeding stored configurations from code, or building automation that tunes agents based on evaluation results.
78
+
79
+ Call `mastra.getEditor()` from anywhere you have access to the `Mastra` instance. It returns the `MastraEditor` instance you registered, with namespaces for each resource type:
80
+
81
+ ```typescript
82
+ import { mastra } from '../mastra'
83
+
84
+ const editor = mastra.getEditor()
85
+ if (!editor) throw new Error('Editor is not registered on Mastra')
86
+
87
+ // Create a stored agent override for an existing code-defined agent
88
+ await editor.agent.create({
89
+ id: 'support-agent',
90
+ instructions: 'You are a friendly support agent for Acme Inc.',
91
+ tools: {
92
+ search_kb: { description: 'Search the Acme knowledge base' },
93
+ },
94
+ })
95
+ ```
96
+
97
+ Use `editor.agent.update()` to change an existing stored configuration. Every update creates a new draft version automatically:
98
+
99
+ ```typescript
100
+ import { mastra } from '../mastra'
101
+
102
+ const editor = mastra.getEditor()!
103
+
104
+ await editor.agent.update({
105
+ id: 'support-agent',
106
+ instructions:
107
+ "You are a friendly support agent for Acme Inc. Always respond in the user's language.",
108
+ })
109
+ ```
110
+
111
+ The `editor.agent` namespace also exposes `getById`, `list`, `listResolved`, and `delete`. The `editor.prompt` namespace exposes the same CRUD methods for prompt blocks. See [Prompts](https://mastra.ai/docs/editor/prompts) for examples.
112
+
113
+ ### Server endpoints
114
+
115
+ The same operations are available over HTTP through the Mastra server. Use these when you want to manage stored agents from a separate service or from a non-TypeScript client:
116
+
117
+ | Method | Path | Description |
118
+ | -------- | ------------------------------- | ------------------------- |
119
+ | `GET` | `/stored/agents` | List all stored agents. |
120
+ | `POST` | `/stored/agents` | Create a stored agent. |
121
+ | `GET` | `/stored/agents/:storedAgentId` | Get a stored agent by ID. |
122
+ | `PATCH` | `/stored/agents/:storedAgentId` | Update a stored agent. |
123
+ | `DELETE` | `/stored/agents/:storedAgentId` | Delete a stored agent. |
124
+
125
+ The Client SDK wraps these endpoints with `client.listStoredAgents()`, `client.createStoredAgent()`, and `client.getStoredAgent()`. Version management endpoints live under `/stored/agents/:storedAgentId/versions`, see [version management](https://mastra.ai/reference/client-js/agents) for the full list.
126
+
127
+ ### Automated experimentation
128
+
129
+ Because stored agents are just data, you can build automation loops that tune agents without human involvement. A common pattern is to pair the editor API with [datasets](https://mastra.ai/docs/evals/datasets/overview) and [experiments](https://mastra.ai/docs/evals/datasets/running-experiments):
130
+
131
+ - Run a dataset through the current version of an agent and score the results.
132
+ - Have another agent read the failing cases and propose changes to the instructions or tools.
133
+ - Apply those changes with `editor.agent.update()` to create a new draft.
134
+ - Re-run the experiment against the draft and compare scores to the baseline.
135
+ - Promote the draft to the published version when the scores improve.
136
+
137
+ This turns agent tuning into a closed feedback loop. One agent owns the production configuration, another agent iterates on it, and every change is versioned so you can roll back if a round of automated edits makes things worse. Combine this with [version targeting](#version-targeting-and-experimentation) to keep production traffic on the published version while the draft is being tested.
138
+
139
+ > **Note:** See the [MastraEditor reference](https://mastra.ai/reference/editor/mastra-editor) for the full namespace API.
140
+
75
141
  ## What can be overridden
76
142
 
77
143
  When you edit a code-defined agent through the editor, only specific fields can be changed:
package/.docs/docs/editor/prompts.md CHANGED
@@ -59,6 +59,69 @@ Rule groups can be nested, so you can combine AND and OR conditions for complex
59
59
 
60
60
  In the Studio, open a block's **Display conditions** panel to set up rules visually. You can also configure conditions programmatically through the API. Blocks without conditions are always included.
61
61
 
62
+ ## Programmatic control
63
+
64
+ Prompt blocks can be managed from code through [`mastra.getEditor().prompt`](https://mastra.ai/reference/editor/mastra-editor). This is useful for seeding a set of starter prompts, syncing blocks between environments, or generating prompt variants from a script.
65
+
66
+ Create a new prompt block with `editor.prompt.create()`:
67
+
68
+ ```typescript
69
+ import { mastra } from '../mastra'
70
+
71
+ const editor = mastra.getEditor()!
72
+
73
+ await editor.prompt.create({
74
+ id: 'brand-voice',
75
+ name: 'Brand voice',
76
+ description: 'Acme Inc. tone and style guidelines',
77
+ content:
78
+ 'You write in a friendly, concise tone. Always address the user as {{userName || "there"}}.',
79
+ })
80
+ ```
81
+
82
+ Update an existing block with `editor.prompt.update()`. Each update creates a new draft version:
83
+
84
+ ```typescript
85
+ import { mastra } from '../mastra'
86
+
87
+ const editor = mastra.getEditor()!
88
+
89
+ await editor.prompt.update({
90
+ id: 'brand-voice',
91
+ content: 'You write in a friendly, concise tone. Always greet the user by name when available.',
92
+ })
93
+ ```
94
+
95
+ Use `editor.prompt.list()` to paginate through stored blocks or `editor.prompt.getById()` to fetch a specific block. To preview an agent's full instructions with a set of prompt blocks applied, call `editor.prompt.preview()` with the draft content.
96
+
97
+ The same operations are available over HTTP through the Mastra server:
98
+
99
+ | Method | Path | Description |
100
+ | -------- | -------------------------------------------- | -------------------------------- |
101
+ | `GET` | `/stored/prompt-blocks` | List all stored prompt blocks. |
102
+ | `POST` | `/stored/prompt-blocks` | Create a stored prompt block. |
103
+ | `GET` | `/stored/prompt-blocks/:storedPromptBlockId` | Get a stored prompt block by ID. |
104
+ | `PATCH` | `/stored/prompt-blocks/:storedPromptBlockId` | Update a stored prompt block. |
105
+ | `DELETE` | `/stored/prompt-blocks/:storedPromptBlockId` | Delete a stored prompt block. |
106
+
107
+ Once a prompt block is created, reference it from an agent's `instructions` field as a `prompt_block_ref`:
108
+
109
+ ```typescript
110
+ import { mastra } from '../mastra'
111
+
112
+ const editor = mastra.getEditor()!
113
+
114
+ await editor.agent.update({
115
+ id: 'support-agent',
116
+ instructions: [
117
+ { type: 'prompt_block_ref', id: 'brand-voice' },
118
+ { type: 'text', content: 'Answer only questions about Acme products.' },
119
+ ],
120
+ })
121
+ ```
122
+
123
+ > **Note:** See the [MastraEditor reference](https://mastra.ai/reference/editor/mastra-editor) for the full `editor.prompt` API.
124
+
62
125
  ## Versioning
63
126
 
64
127
  Prompt blocks follow the same [versioning lifecycle](https://mastra.ai/docs/editor/overview) as agents. Each prompt block has a draft that you can edit and publish as a versioned snapshot. This means prompt content can be versioned and rolled back independently from the agent that uses it.
package/.docs/docs/editor/tools.md CHANGED
@@ -57,7 +57,7 @@ Integration providers connect external tool platforms to the editor. Once regist
57
57
  ```typescript
58
58
  import { Mastra } from '@mastra/core'
59
59
  import { MastraEditor } from '@mastra/editor'
60
- import { ComposioToolProvider } from '@mastra/editor/providers/composio'
60
+ import { ComposioToolProvider } from '@mastra/editor/composio'
61
61
 
62
62
  export const mastra = new Mastra({
63
63
  agents: {
@@ -86,7 +86,7 @@ Integration providers connect external tool platforms to the editor. Once regist
86
86
  ```typescript
87
87
  import { Mastra } from '@mastra/core'
88
88
  import { MastraEditor } from '@mastra/editor'
89
- import { ArcadeToolProvider } from '@mastra/editor/providers/arcade'
89
+ import { ArcadeToolProvider } from '@mastra/editor/arcade'
90
90
 
91
91
  export const mastra = new Mastra({
92
92
  agents: {
package/.docs/docs/observability/tracing/exporters/cloud.md CHANGED
@@ -8,15 +8,24 @@ The `CloudExporter` sends traces to Mastra Cloud for centralized monitoring and
8
8
 
9
9
  1. **Mastra Cloud Account**: Sign up at [cloud.mastra.ai](https://cloud.mastra.ai)
10
10
  2. **Mastra Cloud Project**: Create a project in Mastra Cloud. Traces are scoped per project, so even if you only want observability, you need a project to act as the destination for your traces.
11
- 3. **Access Token**: Generate in your project's sidebar under **Project Settings → Access Tokens**
11
+ 3. **Authentication**: Use either a project-scoped access token or an organization API key. Generate both from Mastra Cloud.
12
12
  4. **Environment Variables**: Set your credentials:
13
13
 
14
14
  ```bash
15
15
  MASTRA_CLOUD_ACCESS_TOKEN=mst_xxxxxxxxxxxxxxxx
16
16
  ```
17
17
 
18
+ If you authenticate with an organization API key, also set the destination project ID:
19
+
20
+ ```bash
21
+ MASTRA_CLOUD_ACCESS_TOKEN=sk_xxxxxxxxxxxxxxxx
22
+ MASTRA_PROJECT_ID=project_123
23
+ ```
24
+
18
25
  ### Basic Setup
19
26
 
27
+ Project-scoped access tokens work without any extra routing configuration:
28
+
20
29
  ```typescript
21
30
  import { Mastra } from '@mastra/core'
22
31
  import { Observability, CloudExporter } from '@mastra/observability'
@@ -35,6 +44,19 @@ export const mastra = new Mastra({
35
44
  })
36
45
  ```
37
46
 
47
+ ### Organization API keys
48
+
49
+ Organization API keys are scoped to the whole org, so the exporter needs a project ID (letters, numbers, hyphens, underscores only) to generate project-scoped collector routes.
50
+
51
+ ```typescript
52
+ new CloudExporter({
53
+ accessToken: process.env.MASTRA_CLOUD_ACCESS_TOKEN,
54
+ projectId: process.env.MASTRA_PROJECT_ID,
55
+ })
56
+ ```
57
+
58
+ When `projectId` is set, base endpoints resolve to `/projects/:projectId/ai/{signal}/publish`. Without it, the exporter keeps using `/ai/{signal}/publish`.
59
+
38
60
  ### Recommended Configuration
39
61
 
40
62
  Include CloudExporter in your observability configuration:
@@ -71,6 +93,10 @@ new CloudExporter({
71
93
  // Optional - defaults to env var
72
94
  accessToken: process.env.MASTRA_CLOUD_ACCESS_TOKEN,
73
95
 
96
+ // Optional - required for organization API keys or any project-scoped collector route
97
+ // Letters, numbers, hyphens, and underscores only
98
+ projectId: process.env.MASTRA_PROJECT_ID,
99
+
74
100
  // Optional - for self-hosted Mastra Cloud
75
101
  endpoint: 'https://cloud.your-domain.com',
76
102
 
@@ -100,7 +126,7 @@ new CloudExporter({
100
126
  - Trace ID
101
127
  - Error status
102
128
 
103
- > **Note:** Traces are scoped to the project that issued the access token. To view traces, make sure you're viewing the same project you generated the token from.
129
+ > **Note:** If you use a project-scoped token, view the project that issued the token. If you use an organization API key, view the project named in `MASTRA_PROJECT_ID` or `projectId`.
104
130
 
105
131
  ### Features
106
132
 
package/.docs/models/gateways/openrouter.md CHANGED
@@ -1,6 +1,6 @@
1
1
  # ![OpenRouter logo](https://models.dev/logos/openrouter.svg)OpenRouter
2
2
 
3
- OpenRouter aggregates models from multiple providers with enhanced features like rate limiting and failover. Access 171 models through Mastra's model router.
3
+ OpenRouter aggregates models from multiple providers with enhanced features like rate limiting and failover. Access 173 models through Mastra's model router.
4
4
 
5
5
  Learn more in the [OpenRouter documentation](https://openrouter.ai/models).
6
6
 
@@ -84,7 +84,9 @@ ANTHROPIC_API_KEY=ant-...
84
84
  | `google/gemma-3n-e4b-it` |
85
85
  | `google/gemma-3n-e4b-it:free` |
86
86
  | `google/gemma-4-26b-a4b-it` |
87
+ | `google/gemma-4-26b-a4b-it:free` |
87
88
  | `google/gemma-4-31b-it` |
89
+ | `google/gemma-4-31b-it:free` |
88
90
  | `inception/mercury` |
89
91
  | `inception/mercury-2` |
90
92
  | `inception/mercury-coder` |
@@ -175,7 +177,7 @@ ANTHROPIC_API_KEY=ant-...
175
177
  | `qwen/qwen3-next-80b-a3b-thinking` |
176
178
  | `qwen/qwen3.5-397b-a17b` |
177
179
  | `qwen/qwen3.5-plus-02-15` |
178
- | `qwen/qwen3.6-plus:free` |
180
+ | `qwen/qwen3.6-plus` |
179
181
  | `sourceful/riverflow-v2-fast-preview` |
180
182
  | `sourceful/riverflow-v2-max-preview` |
181
183
  | `sourceful/riverflow-v2-standard-preview` |
package/.docs/models/index.md CHANGED
@@ -1,6 +1,6 @@
1
1
  # Model Providers
2
2
 
3
- Mastra provides a unified interface for working with LLMs across multiple providers, giving you access to 3584 models from 99 providers through a single API.
3
+ Mastra provides a unified interface for working with LLMs across multiple providers, giving you access to 3589 models from 99 providers through a single API.
4
4
 
5
5
  ## Features
6
6
 
package/.docs/models/providers/cortecs.md CHANGED
@@ -1,6 +1,6 @@
1
1
  # ![Cortecs logo](https://models.dev/logos/cortecs.svg)Cortecs
2
2
 
3
- Access 29 Cortecs models through Mastra's model router. Authentication is handled automatically using the `CORTECS_API_KEY` environment variable.
3
+ Access 30 Cortecs models through Mastra's model router. Authentication is handled automatically using the `CORTECS_API_KEY` environment variable.
4
4
 
5
5
  Learn more in the [Cortecs documentation](https://cortecs.ai).
6
6
 
@@ -62,6 +62,7 @@ for await (const chunk of stream) {
62
62
  | `cortecs/nova-pro-v1` | 300K | | | | | | $1 | $4 |
63
63
  | `cortecs/qwen3-32b` | 16K | | | | | | $0.10 | $0.33 |
64
64
  | `cortecs/qwen3-coder-480b-a35b-instruct` | 262K | | | | | | $0.44 | $2 |
65
+ | `cortecs/qwen3-coder-next` | 256K | | | | | | $0.16 | $0.84 |
65
66
  | `cortecs/qwen3-next-80b-a3b-thinking` | 128K | | | | | | $0.16 | $1 |
66
67
 
67
68
  ## Advanced configuration
package/.docs/models/providers/fireworks-ai.md CHANGED
@@ -1,6 +1,6 @@
1
1
  # ![Fireworks AI logo](https://models.dev/logos/fireworks-ai.svg)Fireworks AI
2
2
 
3
- Access 14 Fireworks AI models through Mastra's model router. Authentication is handled automatically using the `FIREWORKS_API_KEY` environment variable.
3
+ Access 16 Fireworks AI models through Mastra's model router. Authentication is handled automatically using the `FIREWORKS_API_KEY` environment variable.
4
4
 
5
5
  Learn more in the [Fireworks AI documentation](https://fireworks.ai/docs/).
6
6
 
@@ -40,6 +40,7 @@ for await (const chunk of stream) {
40
40
  | `fireworks-ai/accounts/fireworks/models/glm-4p5-air` | 131K | | | | | | $0.22 | $0.88 |
41
41
  | `fireworks-ai/accounts/fireworks/models/glm-4p7` | 198K | | | | | | $0.60 | $2 |
42
42
  | `fireworks-ai/accounts/fireworks/models/glm-5` | 203K | | | | | | $1 | $3 |
43
+ | `fireworks-ai/accounts/fireworks/models/glm-5p1` | 203K | | | | | | $1 | $4 |
43
44
  | `fireworks-ai/accounts/fireworks/models/gpt-oss-120b` | 131K | | | | | | $0.15 | $0.60 |
44
45
  | `fireworks-ai/accounts/fireworks/models/gpt-oss-20b` | 131K | | | | | | $0.05 | $0.20 |
45
46
  | `fireworks-ai/accounts/fireworks/models/kimi-k2-instruct` | 128K | | | | | | $1 | $3 |
@@ -47,6 +48,7 @@ for await (const chunk of stream) {
47
48
  | `fireworks-ai/accounts/fireworks/models/kimi-k2p5` | 256K | | | | | | $0.60 | $3 |
48
49
  | `fireworks-ai/accounts/fireworks/models/minimax-m2p1` | 200K | | | | | | $0.30 | $1 |
49
50
  | `fireworks-ai/accounts/fireworks/models/minimax-m2p5` | 197K | | | | | | $0.30 | $1 |
51
+ | `fireworks-ai/accounts/fireworks/models/qwen3p6-plus` | 128K | | | | | | $0.50 | $3 |
50
52
  | `fireworks-ai/accounts/fireworks/routers/kimi-k2p5-turbo` | 256K | | | | | | — | — |
51
53
 
52
54
  ## Advanced configuration
package/.docs/reference/core/getEditor.md ADDED
@@ -0,0 +1,35 @@
1
+ # Mastra.getEditor()
2
+
3
+ The `.getEditor()` method is used to retrieve the editor instance that has been configured on the Mastra instance. The editor exposes CRUD namespaces for managing stored agents, prompt blocks, MCP clients, scorers, skills, and workspaces programmatically.
4
+
5
+ ## Usage example
6
+
7
+ ```typescript
8
+ import { Mastra } from '@mastra/core'
9
+ import { MastraEditor } from '@mastra/editor'
10
+
11
+ const mastra = new Mastra({
12
+ editor: new MastraEditor(),
13
+ })
14
+
15
+ const editor = mastra.getEditor()
16
+
17
+ const agent = await editor?.agent.create({
18
+ id: 'support-agent',
19
+ name: 'Support Agent',
20
+ instructions: 'Help customers with their questions.',
21
+ })
22
+ ```
23
+
24
+ ## Parameters
25
+
26
+ This method doesn't accept any parameters.
27
+
28
+ ## Returns
29
+
30
+ **editor** (`MastraEditor | undefined`): The configured editor instance, or undefined if no editor has been configured.
31
+
32
+ ## Related
33
+
34
+ - [Editor overview](https://mastra.ai/docs/editor/overview)
35
+ - [MastraEditor reference](https://mastra.ai/reference/editor/mastra-editor)
package/.docs/reference/editor/mastra-editor.md CHANGED
@@ -41,18 +41,96 @@ export const mastra = new Mastra({
41
41
 
42
42
  ## Namespaces
43
43
 
44
- The editor exposes namespaces for managing different entity types. These are used by the Mastra server and Studio — you don't call them directly in application code.
44
+ The editor exposes namespaces for managing different entity types. Access them from any Mastra instance with `mastra.getEditor()` and call the CRUD methods directly in application code, or rely on the Mastra server routes that use them under the hood.
45
+
46
+ All namespaces extend a shared CRUD base class, so they expose the same `create`, `getById`, `update`, `delete`, `list`, `listResolved`, and `clearCache` methods. The namespace-specific property tables below also document any additional methods.
45
47
 
46
48
  **agent** (`EditorAgentNamespace`): CRUD operations and version management for stored agents. Handles applying stored overrides to code-defined agents.
47
49
 
50
+ **agent.create** (`(input: StorageCreateAgentInput) => Promise<Agent>`): Create a new stored agent and return a hydrated Agent instance. Accepts an id, authorId, metadata, and the initial snapshot (name, description, instructions, model, tools, memory, and so on).
51
+
52
+ **agent.getById** (`(id: string, options?: GetByIdOptions) => Promise<Agent | null>`): Return a hydrated Agent instance for a stored agent. Pass options with versionId, versionNumber, or status ("draft" | "published" | "archived") to target a specific version. Default version requests are cached.
53
+
54
+ **agent.update** (`(input: StorageUpdateAgentInput) => Promise<Agent>`): Partially update a stored agent. Creates a new draft version with the provided snapshot fields (instructions, tools, memory, and so on) and invalidates the cache. Set memory to null to disable memory.
55
+
56
+ **agent.delete** (`(id: string) => Promise<void>`): Delete a stored agent and remove it from the Mastra runtime registry.
57
+
58
+ **agent.list** (`(args?: StorageListAgentsInput) => Promise<StorageListAgentsOutput>`): List stored agents with optional pagination, orderBy, authorId, and metadata filters. Returns raw stored snapshots.
59
+
60
+ **agent.listResolved** (`(args?: StorageListAgentsInput) => Promise<StorageListAgentsResolvedOutput>`): Same as list, but returns fully resolved configurations with references dereferenced.
61
+
62
+ **agent.applyStoredOverrides** (`(agent: Agent, options?: { versionId?: string; status?: "draft" | "published" }) => Promise<Agent>`): Mutate a code-defined agent in place to apply any stored overrides (instructions, tools, variables). Called internally by mastra.getAgent() — you rarely call it directly.
63
+
64
+ **agent.clone** (`(agent: Agent, options: { newId: string; newName?: string; metadata?: Record<string, unknown>; authorId?: string; requestContext?: RequestContext; }) => Promise<Agent>`): Create a new stored agent by cloning an existing agent.
65
+
66
+ **agent.clearCache** (`(agentId?: string) => void`): Clear the in-memory cache for one agent or all agents. Called automatically after mutations.
67
+
48
68
  **prompt** (`EditorPromptNamespace`): CRUD operations for prompt blocks. Includes a preview method for resolving instruction blocks with draft content.
49
69
 
70
+ **prompt.create** (`(input: StorageCreatePromptBlockInput) => Promise<StorageResolvedPromptBlockType>`): Create a new stored prompt block. Accepts an id, authorId, metadata, and the initial snapshot (name, description, content, rules, requestContextSchema).
71
+
72
+ **prompt.getById** (`(id: string, options?: GetByIdOptions) => Promise<StorageResolvedPromptBlockType | null>`): Return a resolved prompt block. Pass options to target a specific version or status.
73
+
74
+ **prompt.update** (`(input: StorageUpdatePromptBlockInput) => Promise<StorageResolvedPromptBlockType>`): Partially update a stored prompt block. Creates a new draft version with the provided snapshot fields.
75
+
76
+ **prompt.delete** (`(id: string) => Promise<void>`): Delete a stored prompt block and remove it from the Mastra runtime registry.
77
+
78
+ **prompt.list** (`(args?: StorageListPromptBlocksInput) => Promise<StorageListPromptBlocksOutput>`): List stored prompt blocks with optional pagination, orderBy, authorId, metadata, and status filters.
79
+
80
+ **prompt.listResolved** (`(args?: StorageListPromptBlocksInput) => Promise<StorageListPromptBlocksResolvedOutput>`): Same as list, but returns fully resolved prompt block content.
81
+
82
+ **prompt.preview** (`(blocks: AgentInstructionBlock[], context: Record<string, unknown>) => Promise<string>`): Resolve an array of instruction blocks against a context, rendering template variables and evaluating display conditions. Includes draft content for referenced prompt blocks.
83
+
84
+ **prompt.clearCache** (`(id?: string) => void`): Clear the in-memory cache for one prompt block or all prompt blocks.
85
+
50
86
  **mcp** (`EditorMCPNamespace`): CRUD operations for stored MCP client configurations.
51
87
 
88
+ **mcp.create** (`(input: StorageCreateMCPClientInput) => Promise<MCPClient>`): Create a new stored MCP client. Accepts an id, authorId, metadata, and the initial snapshot (servers, tool filtering).
89
+
90
+ **mcp.getById** (`(id: string, options?: GetByIdOptions) => Promise<MCPClient | null>`): Return a hydrated MCPClient instance for a stored MCP client.
91
+
92
+ **mcp.update** (`(input: StorageUpdateMCPClientInput) => Promise<MCPClient>`): Partially update a stored MCP client and invalidate the cache.
93
+
94
+ **mcp.delete** (`(id: string) => Promise<void>`): Delete a stored MCP client and remove it from the Mastra runtime registry.
95
+
96
+ **mcp.list** (`(args?: StorageListMCPClientsInput) => Promise<StorageListMCPClientsOutput>`): List stored MCP clients with optional pagination and filters.
97
+
98
+ **mcp.listResolved** (`(args?: StorageListMCPClientsInput) => Promise<StorageListMCPClientsResolvedOutput>`): Same as list, but returns fully resolved MCP client configurations.
99
+
100
+ **mcp.clearCache** (`(id?: string) => void`): Clear the in-memory cache for one MCP client or all MCP clients.
101
+
52
102
  **mcpServer** (`EditorMCPServerNamespace`): CRUD operations for MCP server configurations.
53
103
 
104
+ **mcpServer.create** (`(input: StorageCreateMCPServerInput) => Promise<MCPServerBase>`): Create a new stored MCP server configuration and return a hydrated server instance.
105
+
106
+ **mcpServer.getById** (`(id: string, options?: GetByIdOptions) => Promise<MCPServerBase | null>`): Return a hydrated MCP server for a given id.
107
+
108
+ **mcpServer.update** (`(input: StorageUpdateMCPServerInput) => Promise<MCPServerBase>`): Partially update a stored MCP server configuration.
109
+
110
+ **mcpServer.delete** (`(id: string) => Promise<void>`): Delete a stored MCP server configuration.
111
+
112
+ **mcpServer.list** (`(args?: StorageListMCPServersInput) => Promise<StorageListMCPServersOutput>`): List stored MCP server configurations.
113
+
114
+ **mcpServer.listResolved** (`(args?: StorageListMCPServersInput) => Promise<StorageListMCPServersResolvedOutput>`): Same as list, but returns fully resolved server configurations.
115
+
116
+ **mcpServer.clearCache** (`(id?: string) => void`): Clear the in-memory cache for one MCP server or all MCP servers.
117
+
54
118
  **scorer** (`EditorScorerNamespace`): CRUD operations for scorer configurations.
55
119
 
120
+ **scorer.create** (`(input: StorageCreateScorerInput) => Promise<MastraScorer>`): Create a new stored scorer and return a hydrated MastraScorer instance.
121
+
122
+ **scorer.getById** (`(id: string, options?: GetByIdOptions) => Promise<MastraScorer | null>`): Return a hydrated scorer for a given id.
123
+
124
+ **scorer.update** (`(input: StorageUpdateScorerInput) => Promise<MastraScorer>`): Partially update a stored scorer.
125
+
126
+ **scorer.delete** (`(id: string) => Promise<void>`): Delete a stored scorer and remove it from the Mastra runtime registry.
127
+
128
+ **scorer.list** (`(args?: StorageListScorersInput) => Promise<StorageListScorersOutput>`): List stored scorers with optional pagination and filters.
129
+
130
+ **scorer.listResolved** (`(args?: StorageListScorersInput) => Promise<StorageListScorersResolvedOutput>`): Same as list, but returns fully resolved scorer configurations.
131
+
132
+ **scorer.clearCache** (`(id?: string) => void`): Clear the in-memory cache for one scorer or all scorers.
133
+
56
134
  ## Methods
57
135
 
58
136
  ### Provider access
package/.docs/reference/index.md CHANGED
@@ -63,6 +63,7 @@ The Reference section provides documentation of Mastra's API, including paramete
63
63
  - [.getAgent()](https://mastra.ai/reference/core/getAgent)
64
64
  - [.getAgentById()](https://mastra.ai/reference/core/getAgentById)
65
65
  - [.getDeployer()](https://mastra.ai/reference/core/getDeployer)
66
+ - [.getEditor()](https://mastra.ai/reference/core/getEditor)
66
67
  - [.getGateway()](https://mastra.ai/reference/core/getGateway)
67
68
  - [.getGatewayById()](https://mastra.ai/reference/core/getGatewayById)
68
69
  - [.getLogger()](https://mastra.ai/reference/core/getLogger)
package/.docs/reference/observability/tracing/exporters/cloud-exporter.md CHANGED
@@ -24,11 +24,26 @@ interface CloudExporterConfig extends BaseExporterConfig {
24
24
  /** Cloud access token (from env or config) */
25
25
  accessToken?: string
26
26
 
27
+ /** Project ID for project-scoped collector routes (letters, numbers, hyphens, underscores) */
28
+ projectId?: string
29
+
27
30
  /** Base cloud observability endpoint */
28
31
  endpoint?: string
29
32
 
30
33
  /** Explicit cloud traces endpoint override */
31
34
  tracesEndpoint?: string
35
+
36
+ /** Explicit cloud logs endpoint override */
37
+ logsEndpoint?: string
38
+
39
+ /** Explicit cloud metrics endpoint override */
40
+ metricsEndpoint?: string
41
+
42
+ /** Explicit cloud scores endpoint override */
43
+ scoresEndpoint?: string
44
+
45
+ /** Explicit cloud feedback endpoint override */
46
+ feedbackEndpoint?: string
32
47
  }
33
48
  ```
34
49
 
@@ -41,8 +56,9 @@ Extends `BaseExporterConfig`, which includes:
41
56
 
42
57
  The exporter reads these environment variables if not provided in config:
43
58
 
44
- - `MASTRA_CLOUD_ACCESS_TOKEN` - Project-scoped access token for authentication (generate in your Mastra Cloud project under **Project Settings → Access Tokens**)
45
- - `MASTRA_CLOUD_TRACES_ENDPOINT` - Base cloud endpoint (defaults to `https://api.mastra.ai`)
59
+ - `MASTRA_CLOUD_ACCESS_TOKEN` - Authentication token. Project-scoped tokens work with the default `/ai/{signal}/publish` routes. Organization API keys require `projectId` or `MASTRA_PROJECT_ID`.
60
+ - `MASTRA_PROJECT_ID` - Project ID to use when deriving project-scoped collector routes such as `/projects/:projectId/ai/spans/publish`
61
+ - `MASTRA_CLOUD_TRACES_ENDPOINT` - Traces endpoint override. Pass either a base origin or a full traces publish URL. Defaults to `https://api.mastra.ai`
46
62
 
47
63
  ## Properties
48
64
 
@@ -151,6 +167,13 @@ The exporter batches tracing spans, logs, metrics, scores, and feedback for effi
151
167
  - Drops batches after all retries fail
152
168
  - Logs errors but continues processing new events
153
169
 
170
+ ### Endpoint routing
171
+
172
+ - Base origins derive signal endpoints automatically
173
+ - Without `projectId`, derived routes use `/ai/{signal}/publish`
174
+ - With `projectId` or `MASTRA_PROJECT_ID`, derived routes use `/projects/:projectId/ai/{signal}/publish`
175
+ - Explicit full publish URLs are used as-is, even when `projectId` is configured
176
+
154
177
  ### Signal Processing
155
178
 
156
179
  - `exportTracingEvent()` only exports `SPAN_ENDED` tracing events
@@ -192,6 +215,7 @@ const exporter = new CloudExporter()
192
215
  // Explicit configuration
193
216
  const customExporter = new CloudExporter({
194
217
  accessToken: 'your-token',
218
+ projectId: 'project_123',
195
219
  maxBatchSize: 500,
196
220
  maxBatchWaitMs: 2000,
197
221
  logLevel: 'debug',
package/CHANGELOG.md CHANGED
@@ -1,5 +1,12 @@
1
1
  # @mastra/mcp-docs-server
2
2
 
3
+ ## 1.1.24-alpha.1
4
+
5
+ ### Patch Changes
6
+
7
+ - Updated dependencies [[`ef94400`](https://github.com/mastra-ai/mastra/commit/ef9440049402596b31f2ab976c5e4508f6cb6c91)]:
8
+ - @mastra/core@1.24.1-alpha.0
9
+
3
10
  ## 1.1.23
4
11
 
5
12
  ### Patch Changes
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@mastra/mcp-docs-server",
3
- "version": "1.1.23",
3
+ "version": "1.1.24-alpha.1",
4
4
  "description": "MCP server for accessing Mastra.ai documentation, changelogs, and news.",
5
5
  "type": "module",
6
6
  "main": "dist/index.js",
@@ -29,7 +29,7 @@
29
29
  "jsdom": "^26.1.0",
30
30
  "local-pkg": "^1.1.2",
31
31
  "zod": "^4.3.6",
32
- "@mastra/core": "1.24.0",
32
+ "@mastra/core": "1.24.1-alpha.0",
33
33
  "@mastra/mcp": "^1.4.2"
34
34
  },
35
35
  "devDependencies": {
@@ -46,9 +46,9 @@
46
46
  "tsx": "^4.21.0",
47
47
  "typescript": "^5.9.3",
48
48
  "vitest": "4.0.18",
49
+ "@internal/lint": "0.0.81",
49
50
  "@internal/types-builder": "0.0.56",
50
- "@mastra/core": "1.24.0",
51
- "@internal/lint": "0.0.81"
51
+ "@mastra/core": "1.24.1-alpha.0"
52
52
  },
53
53
  "homepage": "https://mastra.ai",
54
54
  "repository": {