@mastra/mcp-docs-server 1.1.37-alpha.1 → 1.1.37-alpha.5

package/.docs/models/providers/nearai.md

@@ -0,0 +1,103 @@
+# ![NEAR AI Cloud logo](https://models.dev/logos/nearai.svg)NEAR AI Cloud
+
+Access 33 NEAR AI Cloud models through Mastra's model router. Authentication is handled automatically using the `NEARAI_API_KEY` environment variable.
+
+Learn more in the [NEAR AI Cloud documentation](https://docs.near.ai/).
+
+```bash
+NEARAI_API_KEY=your-api-key
+```
+
+```typescript
+import { Agent } from "@mastra/core/agent";
+
+const agent = new Agent({
+  id: "my-agent",
+  name: "My Agent",
+  instructions: "You are a helpful assistant",
+  model: "nearai/Qwen/Qwen3-30B-A3B-Instruct-2507"
+});
+
+// Generate a response
+const response = await agent.generate("Hello!");
+
+// Stream a response
+const stream = await agent.stream("Tell me a story");
+for await (const chunk of stream) {
+  console.log(chunk);
+}
+```
+
+> **Info:** Mastra uses the OpenAI-compatible `/chat/completions` endpoint. Some provider-specific features may not be available. Check the [NEAR AI Cloud documentation](https://docs.near.ai/) for details.
+
+## Models
+
+| Model                                      | Context | Tools | Reasoning | Image | Audio | Video | Input $/1M | Output $/1M |
+| ------------------------------------------ | ------- | ----- | --------- | ----- | ----- | ----- | ---------- | ----------- |
+| `nearai/anthropic/claude-haiku-4-5`        | 200K    |       |           |       |       |       | $1         | $5          |
+| `nearai/anthropic/claude-opus-4-6`         | 200K    |       |           |       |       |       | $5         | $25         |
+| `nearai/anthropic/claude-opus-4-7`         | 1.0M    |       |           |       |       |       | $5         | $25         |
+| `nearai/anthropic/claude-sonnet-4-5`       | 200K    |       |           |       |       |       | $3         | $16         |
+| `nearai/anthropic/claude-sonnet-4-6`       | 1.0M    |       |           |       |       |       | $3         | $15         |
+| `nearai/black-forest-labs/FLUX.2-klein-4B` | 128K    |       |           |       |       |       | $1         | $1          |
+| `nearai/google/gemini-2.5-flash`           | 1.0M    |       |           |       |       |       | $0.30      | $3          |
+| `nearai/google/gemini-2.5-flash-lite`      | 1.0M    |       |           |       |       |       | $0.10      | $0.40       |
+| `nearai/google/gemini-2.5-pro`             | 1.0M    |       |           |       |       |       | $1         | $10         |
+| `nearai/google/gemini-3.1-flash-lite`      | 1.0M    |       |           |       |       |       | $0.25      | $2          |
+| `nearai/openai/gpt-4.1`                    | 1.0M    |       |           |       |       |       | $2         | $8          |
+| `nearai/openai/gpt-4.1-mini`               | 1.0M    |       |           |       |       |       | $0.40      | $2          |
+| `nearai/openai/gpt-4.1-nano`               | 1.0M    |       |           |       |       |       | $0.10      | $0.40       |
+| `nearai/openai/gpt-5`                      | 400K    |       |           |       |       |       | $1         | $10         |
+| `nearai/openai/gpt-5-mini`                 | 400K    |       |           |       |       |       | $0.25      | $2          |
+| `nearai/openai/gpt-5-nano`                 | 400K    |       |           |       |       |       | $0.05      | $0.40       |
+| `nearai/openai/gpt-5.1`                    | 400K    |       |           |       |       |       | $1         | $10         |
+| `nearai/openai/gpt-5.2`                    | 400K    |       |           |       |       |       | $2         | $16         |
+| `nearai/openai/gpt-5.4`                    | 1.1M    |       |           |       |       |       | $3         | $15         |
+| `nearai/openai/gpt-5.4-mini`               | 400K    |       |           |       |       |       | $0.75      | $5          |
+| `nearai/openai/gpt-5.4-nano`               | 400K    |       |           |       |       |       | $0.20      | $1          |
+| `nearai/openai/gpt-5.5`                    | 1.1M    |       |           |       |       |       | $5         | $30         |
+| `nearai/openai/gpt-oss-120b`               | 131K    |       |           |       |       |       | $0.15      | $0.55       |
+| `nearai/openai/o3`                         | 200K    |       |           |       |       |       | $2         | $8          |
+| `nearai/openai/o3-mini`                    | 200K    |       |           |       |       |       | $1         | $4          |
+| `nearai/openai/o4-mini`                    | 200K    |       |           |       |       |       | $1         | $4          |
+| `nearai/openai/whisper-large-v3`           | 448     |       |           |       |       |       | $0.01      | —           |
+| `nearai/Qwen/Qwen3-30B-A3B-Instruct-2507`  | 262K    |       |           |       |       |       | $0.15      | $0.55       |
+| `nearai/Qwen/Qwen3-Embedding-0.6B`         | 41K     |       |           |       |       |       | $0.01      | —           |
+| `nearai/Qwen/Qwen3-Reranker-0.6B`          | 41K     |       |           |       |       |       | $0.01      | $0.01       |
+| `nearai/Qwen/Qwen3-VL-30B-A3B-Instruct`    | 256K    |       |           |       |       |       | $0.15      | $0.55       |
+| `nearai/Qwen/Qwen3.5-122B-A10B`            | 131K    |       |           |       |       |       | $0.40      | $3          |
+| `nearai/zai-org/GLM-5.1-FP8`               | 203K    |       |           |       |       |       | $0.85      | $3          |
+
+## Advanced configuration
+
+### Custom headers
+
+```typescript
+const agent = new Agent({
+  id: "custom-agent",
+  name: "custom-agent",
+  model: {
+    url: "https://cloud-api.near.ai/v1",
+    id: "nearai/Qwen/Qwen3-30B-A3B-Instruct-2507",
+    apiKey: process.env.NEARAI_API_KEY,
+    headers: {
+      "X-Custom-Header": "value"
+    }
+  }
+});
+```
+
+### Dynamic model selection
+
+```typescript
+const agent = new Agent({
+  id: "dynamic-agent",
+  name: "Dynamic Agent",
+  model: ({ requestContext }) => {
+    const useAdvanced = requestContext.task === "complex";
+    return useAdvanced
+      ? "nearai/zai-org/GLM-5.1-FP8"
+      : "nearai/Qwen/Qwen3-30B-A3B-Instruct-2507";
+  }
+});
+```

package/.docs/models/providers/opencode.md

@@ -1,6 +1,6 @@
 # ![OpenCode Zen logo](https://models.dev/logos/opencode.svg)OpenCode Zen
 
-Access 40 OpenCode Zen models through Mastra's model router. Authentication is handled automatically using the `OPENCODE_API_KEY` environment variable.
+Access 39 OpenCode Zen models through Mastra's model router. Authentication is handled automatically using the `OPENCODE_API_KEY` environment variable.
 
 Learn more in the [OpenCode Zen documentation](https://opencode.ai/docs/zen).
 
@@ -73,7 +73,6 @@ for await (const chunk of stream) {
 | `opencode/nemotron-3-super-free`  | 205K    |       |           |       |       |       | —          | —           |
 | `opencode/qwen3.5-plus`           | 262K    |       |           |       |       |       | $0.20      | $1          |
 | `opencode/qwen3.6-plus`           | 262K    |       |           |       |       |       | $0.50      | $3          |
-| `opencode/ring-2.6-1t-free`       | 262K    |       |           |       |       |       | —          | —           |
 
 ## Advanced configuration
 
@@ -103,7 +102,7 @@ const agent = new Agent({
   model: ({ requestContext }) => {
     const useAdvanced = requestContext.task === "complex";
     return useAdvanced
-      ? "opencode/ring-2.6-1t-free"
+      ? "opencode/qwen3.6-plus"
       : "opencode/big-pickle";
   }
 });

package/.docs/models/providers/siliconflow.md

@@ -1,6 +1,6 @@
 # ![SiliconFlow logo](https://models.dev/logos/siliconflow.svg)SiliconFlow
 
-Access 74 SiliconFlow models through Mastra's model router. Authentication is handled automatically using the `SILICONFLOW_API_KEY` environment variable.
+Access 76 SiliconFlow models through Mastra's model router. Authentication is handled automatically using the `SILICONFLOW_API_KEY` environment variable.
 
 Learn more in the [SiliconFlow documentation](https://cloud.siliconflow.com/models).
 
@@ -44,6 +44,8 @@ for await (const chunk of stream) {
 | `siliconflow/deepseek-ai/DeepSeek-V3.1-Terminus`       | 164K    |       |           |       |       |       | $0.27      | $1          |
 | `siliconflow/deepseek-ai/DeepSeek-V3.2`                | 164K    |       |           |       |       |       | $0.27      | $0.42       |
 | `siliconflow/deepseek-ai/DeepSeek-V3.2-Exp`            | 164K    |       |           |       |       |       | $0.27      | $0.41       |
+| `siliconflow/deepseek-ai/deepseek-v4-flash`            | 1.0M    |       |           |       |       |       | $0.14      | $0.28       |
+| `siliconflow/deepseek-ai/deepseek-v4-pro`              | 1.0M    |       |           |       |       |       | $2         | $3          |
 | `siliconflow/deepseek-ai/deepseek-vl2`                 | 4K      |       |           |       |       |       | $0.15      | $0.15       |
 | `siliconflow/inclusionAI/Ling-flash-2.0`               | 131K    |       |           |       |       |       | $0.14      | $0.57       |
 | `siliconflow/inclusionAI/Ling-mini-2.0`                | 131K    |       |           |       |       |       | $0.07      | $0.28       |

package/.docs/models/providers/xpersona.md

@@ -0,0 +1,71 @@
+# ![Xpersona logo](https://models.dev/logos/xpersona.svg)Xpersona
+
+Access 1 Xpersona model through Mastra's model router. Authentication is handled automatically using the `XPERSONA_API_KEY` environment variable.
+
+Learn more in the [Xpersona documentation](https://xpersona.co/docs).
+
+```bash
+XPERSONA_API_KEY=your-api-key
+```
+
+```typescript
+import { Agent } from "@mastra/core/agent";
+
+const agent = new Agent({
+  id: "my-agent",
+  name: "My Agent",
+  instructions: "You are a helpful assistant",
+  model: "xpersona/xpersona-frieren-coder"
+});
+
+// Generate a response
+const response = await agent.generate("Hello!");
+
+// Stream a response
+const stream = await agent.stream("Tell me a story");
+for await (const chunk of stream) {
+  console.log(chunk);
+}
+```
+
+> **Info:** Mastra uses the OpenAI-compatible `/chat/completions` endpoint. Some provider-specific features may not be available. Check the [Xpersona documentation](https://xpersona.co/docs) for details.
+
+## Models
+
+| Model                             | Context | Tools | Reasoning | Image | Audio | Video | Input $/1M | Output $/1M |
+| --------------------------------- | ------- | ----- | --------- | ----- | ----- | ----- | ---------- | ----------- |
+| `xpersona/xpersona-frieren-coder` | 128K    |       |           |       |       |       | $2         | $6          |
+
+## Advanced configuration
+
+### Custom headers
+
+```typescript
+const agent = new Agent({
+  id: "custom-agent",
+  name: "custom-agent",
+  model: {
+    url: "https://xpersona.co/v1",
+    id: "xpersona/xpersona-frieren-coder",
+    apiKey: process.env.XPERSONA_API_KEY,
+    headers: {
+      "X-Custom-Header": "value"
+    }
+  }
+});
+```
+
+### Dynamic model selection
+
+```typescript
+const agent = new Agent({
+  id: "dynamic-agent",
+  name: "Dynamic Agent",
+  model: ({ requestContext }) => {
+    const useAdvanced = requestContext.task === "complex";
+    return useAdvanced
+      ? "xpersona/xpersona-frieren-coder"
+      : "xpersona/xpersona-frieren-coder";
+  }
+});
+```

package/.docs/models/providers.md

@@ -67,6 +67,7 @@ Direct access to individual AI model providers. Each provider offers unique mode
 - [Moonshot AI (China)](https://mastra.ai/models/providers/moonshotai-cn)
 - [Morph](https://mastra.ai/models/providers/morph)
 - [NanoGPT](https://mastra.ai/models/providers/nano-gpt)
+- [NEAR AI Cloud](https://mastra.ai/models/providers/nearai)
 - [Nebius Token Factory](https://mastra.ai/models/providers/nebius)
 - [Neuralwatt](https://mastra.ai/models/providers/neuralwatt)
 - [Nova](https://mastra.ai/models/providers/nova)
@@ -105,6 +106,7 @@ Direct access to individual AI model providers. Each provider offers unique mode
 - [Xiaomi Token Plan (China)](https://mastra.ai/models/providers/xiaomi-token-plan-cn)
 - [Xiaomi Token Plan (Europe)](https://mastra.ai/models/providers/xiaomi-token-plan-ams)
 - [Xiaomi Token Plan (Singapore)](https://mastra.ai/models/providers/xiaomi-token-plan-sgp)
+- [Xpersona](https://mastra.ai/models/providers/xpersona)
 - [Z.AI](https://mastra.ai/models/providers/zai)
 - [Z.AI Coding Plan](https://mastra.ai/models/providers/zai-coding-plan)
 - [ZenMux](https://mastra.ai/models/providers/zenmux)

package/.docs/reference/agents/agent.md

@@ -185,6 +185,8 @@ Returns an `AgentThreadSubscription` object with these members:
 
 **description** (`string`): Optional description of the agent's purpose and capabilities.
 
+**metadata** (`Record<string, unknown> | ({ requestContext: RequestContext }) => Record<string, unknown> | Promise<Record<string, unknown>>`): Optional metadata for classifying or filtering the agent in clients. Can be a static record or a function that resolves the metadata from the request context.
+
 **instructions** (`SystemMessage | ({ requestContext: RequestContext }) => SystemMessage | Promise<SystemMessage>`): Instructions that guide the agent's behavior. Can be a string, array of strings, system message object, array of system messages, or a function that returns any of these types dynamically. SystemMessage types: string | string\[] | CoreSystemMessage | CoreSystemMessage\[] | SystemModelMessage | SystemModelMessage\[]
 
 **model** (`MastraLanguageModel | ({ requestContext: RequestContext }) => MastraLanguageModel | Promise<MastraLanguageModel>`): The language model used by the agent. Can be provided statically or resolved at runtime.

package/.docs/reference/agents/getMetadata.md

@@ -0,0 +1,61 @@
+# Agent.getMetadata()
+
+The `.getMetadata()` method retrieves the metadata configured for an agent, resolving it if it's a function. Use metadata to classify agents in clients without encoding that data in the agent ID or name.
+
+## Usage example
+
+```typescript
+await agent.getMetadata()
+```
+
+## Parameters
+
+**options** (`{ requestContext?: RequestContext }`): Optional configuration object containing request context. (Default: `{}`)
+
+**options.requestContext** (`RequestContext`): Request Context passed to dynamic metadata functions. Ignored when metadata is static.
+
+## Returns
+
+**metadata** (`Record<string, unknown> | Promise<Record<string, unknown>>`): The metadata configured for the agent, or \`undefined\` if no metadata was configured. Returns either directly or as a promise that resolves to the metadata when defined as a function.
+
+## Extended usage example
+
+Static metadata:
+
+```typescript
+import { Agent } from '@mastra/core/agent'
+
+export const supportAgent = new Agent({
+  id: 'support-agent',
+  name: 'Support Agent',
+  instructions: 'You help customers with support requests.',
+  model: 'openai/gpt-5.4',
+  metadata: { type: 'support' },
+})
+
+const metadata = supportAgent.getMetadata()
+```
+
+Dynamic metadata resolved from the request context:
+
+```typescript
+import { Agent } from '@mastra/core/agent'
+
+export const supportAgent = new Agent({
+  id: 'support-agent',
+  name: 'Support Agent',
+  instructions: 'You help customers with support requests.',
+  model: 'openai/gpt-5.4',
+  metadata: ({ requestContext }) => ({
+    type: 'support',
+    tenant: requestContext.get('tenant'),
+  }),
+})
+
+const metadata = await supportAgent.getMetadata({ requestContext })
+```
+
+## Related
+
+- [Agents overview](https://mastra.ai/docs/agents/overview)
+- [Request Context](https://mastra.ai/docs/server/request-context)

package/.docs/reference/cli/mastra.md

@@ -600,12 +600,13 @@ It accepts [common flags](#common-flags).
 
 ## `mastra api`
 
-Calls a Mastra runtime server with JSON input and JSON output. Use it for local development servers, deployed Mastra platform projects, or self-hosted Mastra servers.
+Calls a Mastra runtime server with JSON input and JSON output. Use it for local development servers, deployed Mastra platform projects, self-hosted Mastra servers, or hosted Mastra Platform Observability APIs.
 
 ```bash
 mastra api agent list --pretty
 mastra api agent run weather-agent '{"messages":"What is the weather in London?"}'
 mastra api tool execute get-weather '{"location":"San Francisco"}'
+mastra api trace list '{"page":0,"perPage":20}' --pretty
 ```
 
 Use `mastra api <resource> <action> --help` to see examples for a command.
@@ -638,7 +639,7 @@ Errors are written to `stderr` as JSON and return a non-zero exit code:
 
 ### Target resolution
 
-The command resolves the target server in this order:
+For runtime commands, the command resolves the target server in this order:
 
 1. `--url <url>` for an explicit remote or self-hosted server.
 2. `http://localhost:4111` for a local `mastra dev` server.
@@ -646,6 +647,15 @@ The command resolves the target server in this order:
 
 Automatic platform auth is only used when the CLI resolves a Mastra platform target from `.mastra-project.json`. Localhost targets and explicit `--url` targets don't receive automatic credentials. Headers passed with `--header` are sent to any target, including localhost.
 
+For observability commands (`trace`, `log`, `score`, and `metric`), the CLI targets `https://observability.mastra.ai` by default instead of a project deployment URL. It resolves credentials in this order:
+
+1. Explicit `Authorization` and `X-Mastra-Project-Id` headers passed with `--header`.
+2. `MASTRA_PLATFORM_ACCESS_TOKEN` and `MASTRA_PROJECT_ID` from your environment.
+3. Project metadata from `.mastra-project.json` for the project ID.
+4. Your Mastra CLI login token as an auth fallback.
+
+Use `--url` and `--header` when you need to override the default hosted observability target or credentials.
+
 ### Flags
 
 #### `--url <url>`
@@ -701,6 +711,13 @@ List commands accept `page` and `perPage` in the JSON input when the target rout
 
 ```bash
 mastra api score list '{"page":0,"perPage":50}'
+mastra api trace list '{"page":0,"perPage":20}'
+```
+
+Routes that support filters accept them in the same JSON input. For example, observability trace listing supports pagination and route-supported filters:
+
+```bash
+mastra api trace list '{"page":0,"perPage":20,"filters":{"spanType":"agent"}}' --pretty
 ```
 
 ### Get command-specific help
@@ -956,14 +973,27 @@ Lists observability traces. Pass optional JSON input for route-supported filters
 
 ```bash
 mastra api trace list [input]
+mastra api trace list '{"page":0,"perPage":20}' --pretty
+mastra api trace list '{"page":0,"perPage":20}' --verbose --pretty
 ```
 
+`trace list` returns lightweight root span records by default so you can page through traces without fetching large input, output, attributes, or metadata payloads. Pass `--verbose` to fetch the full root span records.
+
 #### `mastra api trace get`
 
-Gets one observability trace by ID.
+Gets a lightweight timeline for one observability trace without fetching full span input, output, attributes, or metadata payloads. Pass `--verbose` to fetch the full trace payload.
 
 ```bash
 mastra api trace get <traceId>
+mastra api trace get <traceId> --verbose
+```
+
+#### `mastra api trace span`
+
+Gets one full span from an observability trace. Use this after `trace get` when you know which span you need to inspect.
+
+```bash
+mastra api trace span <traceId> <spanId>
 ```
 
 #### `mastra api log list`
@@ -974,6 +1004,88 @@ Lists observability logs. Pass optional JSON input for route-supported filters o
 mastra api log list [input]
 ```
 
+#### `mastra api metric aggregate`
+
+Gets a single aggregate metric value.
+
+```bash
+mastra api metric aggregate '{"name":["latency_ms"],"aggregation":"avg"}'
+```
+
+#### `mastra api metric breakdown`
+
+Gets metric values grouped by a label or field.
+
+```bash
+mastra api metric breakdown '{"name":["latency_ms"],"aggregation":"avg","groupBy":["model"],"limit":10}'
+```
+
+#### `mastra api metric timeseries`
+
+Gets metric values over time.
+
+```bash
+mastra api metric timeseries '{"name":["latency_ms"],"aggregation":"avg","interval":"1h"}'
+```
+
+#### `mastra api metric percentiles`
+
+Gets metric percentile values over time. Percentile values use decimals from `0` to `1`.
+
+```bash
+mastra api metric percentiles '{"name":"latency_ms","percentiles":[0.5,0.95,0.99],"interval":"1h"}'
+```
+
+#### `mastra api metric names`
+
+Lists discovered metric names. Pass optional JSON input for prefix search and limit.
+
+```bash
+mastra api metric names '{"prefix":"lat","limit":10}'
+```
+
+#### `mastra api metric label-keys`
+
+Lists label keys for a metric.
+
+```bash
+mastra api metric label-keys '{"metricName":"latency_ms"}'
+```
+
+#### `mastra api metric label-values`
+
+Lists label values for a metric label key. Pass optional prefix and limit values to narrow the result.
+
+```bash
+mastra api metric label-values '{"metricName":"latency_ms","labelKey":"model","prefix":"g","limit":10}'
+```
+
+#### Observability with `curl`
+
+You can call the hosted observability API directly with your platform access token and project ID:
+
+```bash
+curl -sS "https://observability.mastra.ai/api/observability/traces?page=0&perPage=20" \
+  -H "Authorization: Bearer $MASTRA_PLATFORM_ACCESS_TOKEN" \
+  -H "X-Mastra-Project-Id: $MASTRA_PROJECT_ID" | jq
+```
+
+Get a lightweight trace timeline:
+
+```bash
+curl -sS "https://observability.mastra.ai/api/observability/traces/<trace-id>/light" \
+  -H "Authorization: Bearer $MASTRA_PLATFORM_ACCESS_TOKEN" \
+  -H "X-Mastra-Project-Id: $MASTRA_PROJECT_ID" | jq
+```
+
+Get a specific span:
+
+```bash
+curl -sS "https://observability.mastra.ai/api/observability/traces/<trace-id>/spans/<span-id>" \
+  -H "Authorization: Bearer $MASTRA_PLATFORM_ACCESS_TOKEN" \
+  -H "X-Mastra-Project-Id: $MASTRA_PROJECT_ID" | jq
+```
+
 #### `mastra api score create`
 
 Creates an observability score. The input uses the server score body shape; inspect it with `--schema`.

package/.docs/reference/index.md

@@ -13,6 +13,7 @@ The Reference section provides documentation of Mastra's API, including paramete
 - [.getInstructions()](https://mastra.ai/reference/agents/getInstructions)
 - [.getLLM()](https://mastra.ai/reference/agents/getLLM)
 - [.getMemory()](https://mastra.ai/reference/agents/getMemory)
+- [.getMetadata()](https://mastra.ai/reference/agents/getMetadata)
 - [.getModel()](https://mastra.ai/reference/agents/getModel)
 - [.getTools()](https://mastra.ai/reference/agents/getTools)
 - [.getVoice()](https://mastra.ai/reference/agents/getVoice)
@@ -267,6 +268,7 @@ The Reference section provides documentation of Mastra's API, including paramete
 - [PlayAI](https://mastra.ai/reference/voice/playai)
 - [Sarvam](https://mastra.ai/reference/voice/sarvam)
 - [Speechify](https://mastra.ai/reference/voice/speechify)
+- [xAI Realtime](https://mastra.ai/reference/voice/xai-realtime)
 - [.addInstructions()](https://mastra.ai/reference/voice/voice.addInstructions)
 - [.addTools()](https://mastra.ai/reference/voice/voice.addTools)
 - [.answer()](https://mastra.ai/reference/voice/voice.answer)