@mastra/mcp-docs-server 1.2.14-alpha.1 → 1.2.14-alpha.4

package/.docs/docs/observability/integrations/exporters/confident-ai.md

@@ -0,0 +1,140 @@
+> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
+
+# Confident AI exporter
+
+[Confident AI](https://www.confident-ai.com/) is an LLM observability and evaluation platform for teams to build reliable AI applications in both development and production.
+
+The `@mastra/deepeval` package sends your Mastra traces to Confident AI, where you can run metrics against them and track quality over time. It builds on [DeepEval](https://www.confident-ai.com/docs), the open-source evaluation SDK behind the platform.
+
+## Installation
+
+**npm**:
+
+```bash
+npm install @mastra/deepeval@latest
+```
+
+**pnpm**:
+
+```bash
+pnpm add @mastra/deepeval@latest
+```
+
+**Yarn**:
+
+```bash
+yarn add @mastra/deepeval@latest
+```
+
+**Bun**:
+
+```bash
+bun add @mastra/deepeval@latest
+```
+
+## Configuration
+
+### Prerequisites
+
+1. **Confident AI account**: Sign up at [confident-ai.com](https://www.confident-ai.com/)
+2. **API key**: Generate one in your Confident AI project settings
+3. **Environment variables**: Set your credentials:
+
+```bash
+CONFIDENT_API_KEY=confident_proj_xxxxxxxxxxxxx
+
+# Optional
+CONFIDENT_TRACE_ENVIRONMENT=production  # Defaults to "development"
+```
+
+### Zero-Config Setup
+
+With environment variables set, use the exporter with no configuration:
+
+```typescript
+import { Mastra } from '@mastra/core'
+import { Observability } from '@mastra/observability'
+import { DeepEvalExporter } from '@mastra/deepeval'
+
+export const mastra = new Mastra({
+  observability: new Observability({
+    configs: {
+      deepeval: {
+        serviceName: 'my-service',
+        exporters: [new DeepEvalExporter()],
+      },
+    },
+  }),
+})
+```
+
+### Explicit Configuration
+
+You can also pass credentials directly (takes precedence over environment variables):
+
+```typescript
+import { Mastra } from '@mastra/core'
+import { Observability } from '@mastra/observability'
+import { DeepEvalExporter } from '@mastra/deepeval'
+
+export const mastra = new Mastra({
+  observability: new Observability({
+    configs: {
+      deepeval: {
+        serviceName: 'my-service',
+        exporters: [
+          new DeepEvalExporter({
+            apiKey: process.env.CONFIDENT_API_KEY,
+            environment: 'production',
+          }),
+        ],
+      },
+    },
+  }),
+})
+```
+
+### Metric collections
+
+Confident AI evaluates incoming traces against metric collections defined in your project. Attach them at the trace level or per span type. Trace-level metrics run against the whole trace, and per-type metrics run against matching spans.
+
+```typescript
+new DeepEvalExporter({
+  metricCollection: 'trace-metrics', // trace-level
+  llmMetricCollection: 'llm-metrics', // applied to LLM spans
+  agentMetricCollection: 'agent-metrics', // applied to agent spans
+  toolMetricCollectionMap: {
+    search: 'search-tool-metrics', // applied to the "search" tool
+  },
+})
+```
+
+### Complete Configuration
+
+```typescript
+new DeepEvalExporter({
+  apiKey: process.env.CONFIDENT_API_KEY,
+  environment: 'production', // Default: "development"
+  name: 'my-trace', // Default: the Mastra serviceName
+  tags: ['production'],
+  metadata: { team: 'growth' },
+})
+```
+
+## Span type mapping
+
+Mastra spans map to the span types shown in Confident AI:
+
+| Mastra span type                                                       | Confident AI span type |
+| ---------------------------------------------------------------------- | ---------------------- |
+| `AGENT_RUN`, `WORKFLOW_RUN`                                            | `AGENT`                |
+| `MODEL_GENERATION`                                                     | `LLM`                  |
+| `TOOL_CALL`, `MCP_TOOL_CALL`, `PROVIDER_TOOL_CALL`, `CLIENT_TOOL_CALL` | `TOOL`                 |
+| `RAG_EMBEDDING`, `RAG_VECTOR_OPERATION`                                | `RETRIEVER`            |
+| All other exported span types                                          | `CUSTOM`               |
+
+## Related
+
+- [Tracing Overview](https://mastra.ai/docs/observability/tracing/overview)
+- [DeepEvalExporter reference](https://mastra.ai/reference/observability/tracing/exporters/confident-ai)
+- [Confident AI documentation](https://www.confident-ai.com/docs)

package/.docs/docs/observability/integrations/overview.md

@@ -41,7 +41,7 @@ Processors transform or redact spans before export:
 
 ## Next steps
 
-- [Configuration](https://mastra.ai/docs/observability/config)
+- [Configuration](https://mastra.ai/docs/observability/overview)
 - [Tracing](https://mastra.ai/docs/observability/tracing/overview)
 - [Mastra Storage](https://mastra.ai/docs/observability/integrations/exporters/mastra-storage)
 - [OpenTelemetry bridge](https://mastra.ai/docs/observability/integrations/bridges/otel)

package/.docs/docs/observability/overview.md

@@ -4,8 +4,8 @@
 
 Mastra's observability system gives you visibility into every agent run, workflow step, tool call, and model interaction. Agent behavior depends on model responses, prompts, tools, memory, and workflow state, so observability helps you inspect runtime decisions from day one. It captures complementary signals that work together to help you understand what your application is doing and why.
 
-- [**Configuration**](https://mastra.ai/docs/observability/config): Configure observability once for traces, logs, metrics, and feedback.
-- [**Storage**](https://mastra.ai/docs/observability/storage): Choose storage backends for persisted traces, logs, metrics aggregation, and feedback queries.
+- [**Configuration**](#configuration): Configure observability once for traces, logs, metrics, and feedback.
+- [**Storage**](#storage): Choose storage backends for persisted traces, logs, metrics aggregation, and feedback queries.
 - [**Tracing**](https://mastra.ai/docs/observability/tracing/overview): Records every operation as a hierarchical timeline of spans, capturing inputs, outputs, token usage, and timing.
 - [**Logging**](https://mastra.ai/docs/observability/logging): Forwards structured log entries from your application and Mastra internals to observability storage, correlated to traces automatically.
 - [**Metrics**](https://mastra.ai/docs/observability/metrics/overview): Extracts trace usage and cost data. No additional instrumentation is required.
@@ -96,21 +96,137 @@ export const mastra = new Mastra({
         spanOutputProcessors: [
           new SensitiveDataFilter(), // Redacts sensitive data like passwords, tokens, keys
         ],
+        logging: {
+          enabled: true,
+          level: 'info',
+        },
       },
     },
   }),
 })
 ```
 
-It enables tracing, log forwarding, and metrics. Mastra also supports external tracing providers like Langfuse, Datadog, and any OpenTelemetry-compatible platform. Use [Configuration](https://mastra.ai/docs/observability/config), [Storage](https://mastra.ai/docs/observability/storage), and [Integrations overview](https://mastra.ai/docs/observability/integrations/overview) to set up observability.
+It enables tracing, log forwarding, and metrics. Mastra also supports external tracing providers like Langfuse, Datadog, and any OpenTelemetry-compatible platform. See [Maintaining Studio access](#maintaining-studio-access) to keep Mastra Studio access while sending data to an external provider.
 
-## Mastra platform
+## Configuration
 
-For hosted traces, logs, and metrics across projects and deploys, see [Observability on Mastra platform](https://mastra.ai/docs/mastra-platform/observability).
+Observability is configured once on your Mastra instance and applies across traces, logs, and metrics.
+
+### Basic config
+
+An observability config usually contains:
+
+- `serviceName`: The service identifier attached to exported observability data.
+- `exporters`: One or more destinations for traces, logs, and derived metrics.
+- `spanOutputProcessors`: Transformations that run before spans are exported.
+- `logging`: Log forwarding settings for observability storage.
+
+For destinations and processors, see [Integrations overview](https://mastra.ai/docs/observability/integrations/overview).
+
+### Maintaining Studio access
+
+When you add external exporters, keep `MastraStorageExporter` for Studio observability and/or `MastraPlatformExporter` for hosted Mastra platform observability.
+
+The following example shows only the observability config. Configure storage separately.
+
+```ts
+import { Observability, MastraStorageExporter, MastraPlatformExporter } from '@mastra/observability'
+import { ArizeExporter } from '@mastra/arize'
+
+export const observability = new Observability({
+  configs: {
+    production: {
+      serviceName: 'my-service',
+      exporters: [
+        new ArizeExporter({
+          endpoint: process.env.PHOENIX_COLLECTOR_ENDPOINT,
+          apiKey: process.env.PHOENIX_API_KEY,
+        }),
+        new MastraStorageExporter(),
+        new MastraPlatformExporter(),
+      ],
+    },
+  },
+})
+```
+
+### Flushing in serverless environments
+
+In serverless environments, flush observability exporters before the runtime pauses or exits:
+
+```ts
+await mastra.observability.flush()
+```
+
+Use external storage in serverless environments instead of local file storage. See [Storage](#storage) for storage selection and routing.
+
+### Multi-config setup
+
+Use multiple configs when different environments or request types need different exporters or sampling behavior. Select the active config at runtime with `configSelector`.
+
+```ts
+import { Mastra } from '@mastra/core'
+import { Observability, MastraStorageExporter } from '@mastra/observability'
+import { LangfuseExporter } from '@mastra/langfuse'
+
+const storageExporter = new MastraStorageExporter()
+const langfuseExporter = new LangfuseExporter()
+
+export const mastra = new Mastra({
+  observability: new Observability({
+    configs: {
+      development: {
+        serviceName: 'my-service-dev',
+        exporters: [storageExporter],
+      },
+      production: {
+        serviceName: 'my-service-prod',
+        exporters: [storageExporter, langfuseExporter],
+      },
+    },
+    configSelector: () => process.env.NODE_ENV || 'development',
+  }),
+})
+```
+
+For trace sampling, see [Tracing](https://mastra.ai/docs/observability/tracing/overview).
 
 ## Storage
 
-Not all storage backends support every signal. Traces work with most backends, but metrics and logs require an OLAP-capable store like DuckDB (development) or ClickHouse (production). For setup guidance, see [Storage](https://mastra.ai/docs/observability/storage).
+Storage determines which observability signals persist, which queries are available, and whether metrics aggregation works. Use a dedicated observability store instead of your primary application store.
+
+### Signal support
+
+Storage support depends on the signal and workload. `MastraStorageExporter` can persist traces to ClickHouse, PostgreSQL, MSSQL, MongoDB, and LibSQL. Metrics require an analytics-capable store:
+
+- DuckDB: Recommended for local testing and development.
+- ClickHouse: Recommended for high-volume production observability.
+- `PostgresStoreVNext`: Supports metrics when the observability domain is enabled. Always provide a time range to avoid full partition scans.
+- Mastra platform: Use `MastraPlatformExporter` for hosted observability without managing the backend yourself.
+
+For the complete provider list and supported tracing strategies, see [Mastra Storage exporter](https://mastra.ai/docs/observability/integrations/exporters/mastra-storage). Use composite storage to route the `observability` domain separately when your primary store doesn't support observability or when the workload needs independent scaling.
+
+### Local development
+
+For local development, use:
+
+- `LibSQLStore` for primary application storage
+- `DuckDBStore` for the `observability` domain
+- `MastraStorageExporter` for local Studio access
+
+### Production deployment
+
+Observability traffic is usually more write-heavy than the rest of the application. In production:
+
+- Use `MastraStorageExporter` with ClickHouse for the `observability` domain when you keep observability in your own storage.
+- Use `MastraPlatformExporter` for hosted Mastra platform observability instead of managing the backend yourself.
+- Use composite storage when observability needs a different backend or scaling policy from your primary application data.
+
+For backend compatibility details and exporter batching behavior, see [Mastra Storage exporter](https://mastra.ai/docs/observability/integrations/exporters/mastra-storage).
+
+## Mastra platform
+
+For hosted traces, logs, and metrics across projects and deploys, see [Observability on Mastra platform](https://mastra.ai/docs/mastra-platform/observability).
 
 ## Next steps
 
@@ -118,8 +234,6 @@ Not all storage backends support every signal. Traces work with most backends, b
 - [Logging](https://mastra.ai/docs/observability/logging)
 - [Metrics](https://mastra.ai/docs/observability/metrics/overview)
 - [Feedback](https://mastra.ai/docs/observability/feedback)
-- [Configuration](https://mastra.ai/docs/observability/config)
-- [Storage](https://mastra.ai/docs/observability/storage)
 - [Integrations overview](https://mastra.ai/docs/observability/integrations/overview)
 - [Mastra Studio](https://mastra.ai/docs/studio/observability)
 - [Automatic metrics reference](https://mastra.ai/reference/observability/metrics/automatic-metrics)

package/.docs/docs/observability/tracing/overview.md

@@ -19,8 +19,8 @@ This page focuses on trace-specific concepts: span hierarchy, sampling, metadata
 
 To get started with tracing, configure observability in your Mastra instance and run an agent or workflow. You can configure behavior through the following features:
 
-- [Configuration](https://mastra.ai/docs/observability/config): Base observability config and multiple configs, plus serverless flushing
-- [Storage](https://mastra.ai/docs/observability/storage): Storage routing for traces, logs, and metrics
+- [Configuration](https://mastra.ai/docs/observability/overview): Base observability config and multiple configs, plus serverless flushing
+- [Storage](https://mastra.ai/docs/observability/overview): Storage routing for traces, logs, and metrics
 - [Integrations overview](https://mastra.ai/docs/observability/integrations/overview): Exporters, bridges, and processors
 
 ## Sampling strategies

package/.docs/docs/server/mastra-client.md

@@ -73,7 +73,7 @@ The Mastra Client SDK exposes all resources served by the Mastra Server.
 
 Use `upsertStoredWorkflow()` to create or replace a persisted workflow definition. A successful upsert validates the complete definition, registers it with the running Mastra instance, and makes it available through the standard workflow execution API.
 
-The following example creates a mapping workflow, reads the stored definition, runs it, and then deletes it:
+The following example shows the full lifecycle of a mapping workflow, from creation and inspection through execution and deletion:
 
 ```typescript
 import { MastraClient } from '@mastra/client-js'

package/.docs/docs/server/server-adapters.md

@@ -4,6 +4,8 @@
 
 Server adapters let you run Mastra with your own HTTP server instead of the Hono server generated by `mastra build`. They provide more control over the server setup, including custom middleware ordering, authentication, logging, and deployment configuration. You can still integrate Mastra into any Node.js application without changing how agents or workflows execute.
 
+> **Warning:** Server adapters use the `mastra` instance you pass them and don't run file-based discovery. Register agents on that instance in code. To use file-based agents, run Mastra as a separate server with `mastra dev` or `mastra build`.
+
 ## When to use server adapters
 
 - You want Mastra’s endpoints added automatically to an existing application

package/.docs/docs/storage/overview.md

@@ -184,7 +184,7 @@ export const mastra = new Mastra({
 })
 ```
 
-You can also route `observability` to a dedicated analytics backend. See [observability storage](https://mastra.ai/docs/observability/storage) for an observability-specific example.
+You can also route `observability` to a dedicated analytics backend. See the [observability quickstart](https://mastra.ai/docs/observability/overview) for an observability-specific example.
 
 ## Supported providers
 
@@ -211,4 +211,4 @@ Each provider page includes installation instructions, configuration parameters,
 - [Storage retention](https://mastra.ai/reference/storage/retention)
 - [Storage schemas](https://mastra.ai/reference/storage/overview)
 - [Memory](https://mastra.ai/docs/memory/overview)
-- [Observability storage](https://mastra.ai/docs/observability/storage)
+- [Observability storage](https://mastra.ai/docs/observability/overview)

package/.docs/docs/workflows/agents-and-tools.md

@@ -108,6 +108,23 @@ export const testWorkflow = createWorkflow({})
 
 The `structuredOutput.schema` option accepts any Standard JSON Schema. The agent will generate output conforming to this schema, and the step's `outputSchema` will be automatically set to match. Visit [Structured Output](https://mastra.ai/docs/agents/structured-output) for more options like error handling strategies and streaming with structured output.
 
+### The `.agent()` shorthand
+
+Add an agent directly with `.agent()` instead of wrapping it in `createStep()`. It accepts the same options as `createStep(agent, options)`, plus an agent ID string in place of the instance:
+
+```typescript
+import { testAgent } from '../agents/test-agent'
+
+export const testWorkflow = createWorkflow({})
+  .map(async ({ inputData }) => ({
+    prompt: `Generate an article about: ${inputData.topic}`,
+  }))
+  .agent(testAgent, { structuredOutput: { schema: articleSchema } })
+  .commit()
+```
+
+`.agent()` records a declarative entry in the workflow graph rather than an opaque step, so workflows built this way can be persisted as [stored workflows](https://mastra.ai/docs/workflows/stored-workflows). Visit [Workflow.agent()](https://mastra.ai/reference/workflows/workflow-methods/agent) for all parameters.
+
 ## Using tools in workflows
 
 Use tools in workflow steps to use existing tool logic. Call from a step's `.execute()` function when you need to prepare context or process responses. Compose tools as steps when you don't need to modify how the tool is used.
@@ -157,6 +174,18 @@ export const testWorkflow = createWorkflow({})
 
 Visit [Input Data Mapping](https://mastra.ai/docs/workflows/control-flow) for more information.
 
+### The `.tool()` shorthand
+
+Add a tool directly with `.tool()` instead of wrapping it in `createStep()`. It accepts a tool instance or a registered tool ID string, plus step-level `retries` and `metadata`:
+
+```typescript
+import { testTool } from '../tools/test-tool'
+
+export const testWorkflow = createWorkflow({}).then(step1).tool(testTool).commit()
+```
+
+Like `.agent()`, `.tool()` records a declarative entry, so the workflow can be persisted as a [stored workflow](https://mastra.ai/docs/workflows/stored-workflows). Visit [Workflow.tool()](https://mastra.ai/reference/workflows/workflow-methods/tool) for all parameters.
+
 ## Related
 
 - [Using Agents](https://mastra.ai/docs/agents/overview)

package/.docs/docs/workflows/stored-workflows.md

@@ -0,0 +1,146 @@
+> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
+
+# Stored workflows
+
+> **Beta:** This feature is in beta. Breaking changes may occur without a major version bump until the API is stable.
+
+Stored workflows are workflow definitions expressed as data instead of code. A definition is a JSON document that describes the workflow's schemas and step graph. Mastra validates the definition and registers it as a runnable workflow, then persists it in storage so it survives process restarts.
+
+Because a definition contains no JavaScript closures, anything that can produce JSON can author a workflow: an HTTP client, an LLM, a visual editor, or your own tooling. Once registered, a stored workflow runs through the same execution API as a code-defined workflow.
+
+## When to use stored workflows
+
+Use stored workflows when users, agents, visual editors, or external systems need to create workflows without changing application code or deploying again.
+
+Keep defining workflows with [`createWorkflow()`](https://mastra.ai/docs/workflows/overview) when the workflow belongs in your application source or needs custom step functions. Stored workflows can invoke agents, tools, and workflows that are already registered on the `Mastra` instance.
+
+## Quickstart
+
+The following example registers a tool and invokes it from a stored workflow. It then runs the workflow. `LibSQLStore` persists the definition in `mastra.db`, so Mastra can restore it after a restart.
+
+```typescript
+import { Mastra } from '@mastra/core/mastra'
+import { createTool } from '@mastra/core/tools'
+import { LibSQLStore } from '@mastra/libsql'
+import { z } from 'zod'
+
+const greetingTool = createTool({
+  id: 'create-greeting',
+  description: 'Create a greeting for a name',
+  inputSchema: z.object({
+    name: z.string(),
+  }),
+  outputSchema: z.object({
+    message: z.string(),
+  }),
+  execute: async ({ name }) => ({
+    message: `Hello, ${name}!`,
+  }),
+})
+
+const mastra = new Mastra({
+  storage: new LibSQLStore({
+    id: 'mastra-storage',
+    url: 'file:./mastra.db',
+  }),
+  tools: { 'create-greeting': greetingTool },
+})
+
+await mastra.addStoredWorkflow({
+  id: 'greeting-workflow',
+  description: 'Create a greeting for the supplied name',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      name: { type: 'string' },
+    },
+    required: ['name'],
+  },
+  outputSchema: {
+    type: 'object',
+    properties: {
+      message: { type: 'string' },
+    },
+    required: ['message'],
+  },
+  graph: [
+    {
+      type: 'tool',
+      id: 'greet',
+      toolId: 'create-greeting',
+    },
+  ],
+})
+
+const workflow = mastra.getWorkflow('greeting-workflow')
+const run = await workflow.createRun()
+const result = await run.start({
+  inputData: { name: 'Ada' },
+})
+
+if (result.status === 'success') {
+  console.log(result.result.message)
+}
+```
+
+The workflow prints `Hello, Ada!`. Calling [`addStoredWorkflow()`](https://mastra.ai/reference/core/addStoredWorkflow) validates the definition before it changes storage or the live workflow registry.
+
+The definition uses JSON Schema because it must survive a JSON round trip. The `graph` describes which registered components to invoke and how data moves between them. See the [stored workflow definition reference](https://mastra.ai/reference/workflows/stored-workflow-definition) for every field and graph entry.
+
+## Build and update definitions
+
+A definition can come from any source that produces JSON. For example, an API route can accept a definition created by a visual editor and register it directly:
+
+```typescript
+const definition = await request.json()
+await mastra.addStoredWorkflow(definition)
+```
+
+### Register dependencies first
+
+Register referenced components on the same `Mastra` instance before adding the stored workflow. Agent and nested workflow entries use their intrinsic IDs. A tool entry uses its key from the `Mastra` `tools` object, so the quickstart registers the tool under `create-greeting` before referencing that key with `toolId`.
+
+Use a `mapping` entry when one step's output doesn't match the next step's input. Mapping entries can read data from the workflow input and previous step results, along with workflow state and request context. The [definition reference](https://mastra.ai/reference/workflows/stored-workflow-definition) lists the supported mapping descriptors.
+
+### Replace a workflow
+
+Add a new definition with the same `id` to replace the persisted definition and live registration:
+
+```typescript
+await mastra.addStoredWorkflow(updatedDefinition)
+```
+
+New runs use the updated graph. Runs that already started continue with their original graph.
+
+### Add nested workflows together
+
+When a root workflow references helper workflows that aren't registered yet, add the full set with [`addStoredWorkflows()`](https://mastra.ai/reference/core/addStoredWorkflows):
+
+```typescript
+await mastra.addStoredWorkflows([rootDefinition, helperDefinition])
+```
+
+Mastra validates the bundle as a unit and determines the registration order from the dependencies. If validation fails, none of the definitions are registered.
+
+### Manage definitions over HTTP
+
+Applications don't need direct access to the `Mastra` instance to manage stored workflows. Use one of these interfaces:
+
+- [Client SDK workflows API](https://mastra.ai/reference/client-js/workflows): Call `upsertStoredWorkflow()` from a JavaScript or TypeScript client.
+- [Server routes](https://mastra.ai/reference/server/routes): Send definitions to `POST /api/stored/workflows`.
+
+On authenticated servers, stored-workflow management requires the `stored-workflows:read` and `stored-workflows:write` permissions. Running the registered workflow requires `workflows:execute`.
+
+### Persist definitions
+
+Stored definitions use the `workflowDefinitions` storage domain. On startup, Mastra loads active definitions from storage and registers them in dependency order.
+
+Without a storage adapter that supports this domain, `addStoredWorkflow()` still registers the workflow in memory, but the definition is lost when the process restarts. See the [storage reference](https://mastra.ai/reference/storage/overview) for adapter support.
+
+## Related
+
+- [Stored workflow definition](https://mastra.ai/reference/workflows/stored-workflow-definition)
+- [`Mastra.addStoredWorkflow()`](https://mastra.ai/reference/core/addStoredWorkflow)
+- [`Mastra.addStoredWorkflows()`](https://mastra.ai/reference/core/addStoredWorkflows)
+- [Client SDK workflows API](https://mastra.ai/reference/client-js/workflows)
+- [Server routes](https://mastra.ai/reference/server/routes)