@mastra/mcp-docs-server 1.1.7-alpha.0 → 1.1.8-alpha.0

package/.docs/docs/agents/agent-approval.md

@@ -1,10 +1,29 @@
-# Agent Approval
+# Agent approval
 
-Agents sometimes require the same [human-in-the-loop](https://mastra.ai/docs/workflows/human-in-the-loop) oversight used in workflows when calling tools that handle sensitive operations, like deleting resources or performing running long processes. With agent approval you can suspend a tool call and provide feedback to the user, or approve or decline a tool call based on targeted application conditions.
+Agents sometimes require the same [human-in-the-loop](https://mastra.ai/docs/workflows/human-in-the-loop) oversight used in workflows when calling tools that handle sensitive operations, like deleting resources or running long processes. With agent approval you can suspend a tool call before it executes so a human can approve or decline it, or let tools suspend themselves to request additional context from the user.
 
-## Tool call approval
+## How approval works
 
-Tool call approval can be enabled at the agent level and apply to every tool the agent uses, or at the tool level providing more granular control over individual tool calls.
+Mastra offers two distinct mechanisms for pausing tool calls: **pre-execution approval** and **runtime suspension**.
+
+### Pre-execution approval
+
+Pre-execution approval pauses a tool call _before_ its `execute` function runs. The LLM still decides which tool to call and provides arguments, but `execute` doesn't run until you explicitly approve.
+
+Two flags control this, combined with OR logic. If _either_ is `true`, the call pauses:
+
+| Flag                        | Where to set it                   | Scope                                       |
+| --------------------------- | --------------------------------- | ------------------------------------------- |
+| `requireToolApproval: true` | `stream()` / `generate()` options | Pauses **every** tool call for that request |
+| `requireApproval: true`     | `createTool()` definition         | Pauses calls to **that specific tool**      |
+
+The stream emits a `tool-call-approval` chunk when a call is paused this way. You then call `approveToolCall()` or `declineToolCall()` to continue.
+
+### Runtime suspension with `suspend()`
+
+A tool can also pause _during_ its `execute` function by calling `suspend()`. This is useful when the tool starts running and then discovers it needs additional user input or confirmation before it can finish.
+
+The stream emits a `tool-call-suspended` chunk with a custom payload defined by the tool's `suspendSchema`. You resume by calling `resumeStream()` with data matching the tool's `resumeSchema`.
 
 ### Storage
 
@@ -24,7 +43,7 @@ export const mastra = new Mastra({
 
 ## Agent-level approval
 
-When calling an agent using `.stream()` set `requireToolApproval` to `true` which will prevent the agent from calling any of the tools defined in its configuration.
+Pass `requireToolApproval: true` to `stream()` or `generate()` to pause every tool call before execution. The LLM still decides which tools to call and with what arguments but no tool runs until you approve or decline.
 
 ```typescript
 const stream = await agent.stream("What's the weather in London?", {
@@ -32,9 +51,20 @@ const stream = await agent.stream("What's the weather in London?", {
 })
 ```
 
+When a tool call is paused, the stream emits a `tool-call-approval` chunk containing the `toolCallId`, `toolName`, and `args`. Use this to inspect the pending call and decide whether to approve or decline:
+
+```typescript
+for await (const chunk of stream.fullStream) {
+  if (chunk.type === 'tool-call-approval') {
+    console.log('Tool:', chunk.payload.toolName)
+    console.log('Args:', chunk.payload.args)
+  }
+}
+```
+
 ### Approving tool calls
 
-To approve a tool call, access `approveToolCall` from the `agent`, passing in the `runId` of the stream. This will let the agent know its now OK to call its tools.
+Call `approveToolCall()` on the agent with the `runId` of the stream to resume the suspended tool call and let it execute:
 
 ```typescript
 const handleApproval = async () => {
@@ -49,7 +79,7 @@ const handleApproval = async () => {
 
 ### Declining tool calls
 
-To decline a tool call, access the `declineToolCall` from the `agent`. You will see the streamed response from the agent, but it won't call its tools.
+Call `declineToolCall()` on the agent to skip the tool call. The agent continues without executing the tool and responds accordingly:
 
 ```typescript
 const handleDecline = async () => {
@@ -64,19 +94,19 @@ const handleDecline = async () => {
 
 ## Tool approval with generate()
 
-Tool approval also works with the `generate()` method for non-streaming use cases. When using `generate()` with `requireToolApproval: true`, the method returns immediately when a tool requires approval instead of executing it.
+Tool approval also works with the `generate()` method for non-streaming use cases. When a tool requires approval during a `generate()` call, the method returns immediately instead of executing the tool.
 
 ### How it works
 
 When a tool requires approval during a `generate()` call, the response includes:
 
-- `finishReason: 'suspended'` - indicates the agent is waiting for approval
-- `suspendPayload` - contains tool call details (`toolCallId`, `toolName`, `args`)
-- `runId` - needed to approve or decline the tool call
+- `finishReason: 'suspended'`: Indicates the agent is waiting for approval
+- `suspendPayload`: Contains tool call details (`toolCallId`, `toolName`, `args`)
+- `runId`: Needed to approve or decline the tool call
 
 ### Approving tool calls
 
-To approve a tool call with `generate()`, use the `approveToolCallGenerate` method:
+Use `approveToolCallGenerate()` to approve the tool call and get the final result:
 
 ```typescript
 const output = await agent.generate('Find user John', {
@@ -99,7 +129,7 @@ if (output.finishReason === 'suspended') {
 
 ### Declining tool calls
 
-To decline a tool call, use the `declineToolCallGenerate` method:
+Use `declineToolCallGenerate()` to skip the tool call:
 
 ```typescript
 if (output.finishReason === 'suspended') {
@@ -108,12 +138,12 @@ if (output.finishReason === 'suspended') {
     toolCallId: output.suspendPayload.toolCallId,
   })
 
-  // Agent will respond acknowledging the declined tool
+  // Agent responds acknowledging the declined tool
   console.log(result.text)
 }
 ```
 
-### Stream vs Generate comparison
+### Stream vs generate comparison
 
 | Aspect             | `stream()`                   | `generate()`                                     |
 | ------------------ | ---------------------------- | ------------------------------------------------ |
@@ -125,11 +155,11 @@ if (output.finishReason === 'suspended') {
 
 ## Tool-level approval
 
-There are two types of tool call approval. The first uses `requireApproval`, which is a property on the tool definition, while `requireToolApproval` is a parameter passed to `agent.stream()`. The second uses `suspend` and lets the agent provide context or confirmation prompts so the user can decide whether the tool call should continue.
+Instead of pausing every tool call at the agent level, you can mark individual tools as requiring approval. This gives you granular control — only specific tools pause, while others execute immediately.
 
-### Tool approval using `requireToolApproval`
+### Approval using `requireApproval`
 
-In this approach, `requireApproval` is configured on the tool definition (shown below) rather than on the agent.
+Set `requireApproval: true` on a tool definition. The tool pauses before execution regardless of whether `requireToolApproval` is set on the agent:
 
 ```typescript
 export const testTool = createTool({
@@ -154,30 +184,30 @@ export const testTool = createTool({
 })
 ```
 
-When `requireApproval` is true for a tool, the stream will include chunks of type `tool-call-approval` to indicate that the call is paused. To continue the call, invoke `resumeStream` with the required `resumeSchema` and the `runId`.
+When `requireApproval` is `true`, the stream emits `tool-call-approval` chunks the same way agent-level approval does. Use `approveToolCall()` or `declineToolCall()` to continue:
 
 ```typescript
 const stream = await agent.stream("What's the weather in London?")
 
 for await (const chunk of stream.fullStream) {
   if (chunk.type === 'tool-call-approval') {
-    console.log('Approval required.')
+    console.log('Approval required for:', chunk.payload.toolName)
   }
 }
 
-const handleResume = async () => {
-  const resumedStream = await agent.resumeStream({ approved: true }, { runId: stream.runId })
+const handleApproval = async () => {
+  const approvedStream = await agent.approveToolCall({ runId: stream.runId })
 
-  for await (const chunk of resumedStream.textStream) {
+  for await (const chunk of approvedStream.textStream) {
     process.stdout.write(chunk)
   }
   process.stdout.write('\n')
 }
 ```
 
-### Tool approval using `suspend`
+### Approval using `suspend`
 
-With this approach, neither the agent nor the tool uses `requireApproval`. Instead, the tool implementation calls `suspend` to pause execution and return context or confirmation prompts to the user.
+With this approach, neither the agent nor the tool uses `requireApproval`. Instead, the tool's `execute` function calls `suspend` to pause at a specific point and return context or confirmation prompts to the user. This is useful when approval depends on runtime conditions rather than being unconditional.
 
 ```typescript
 export const testToolB = createTool({
@@ -210,7 +240,7 @@ export const testToolB = createTool({
 })
 ```
 
-With this approach the stream will include a `tool-call-suspended` chunk, and the `suspendPayload` will contain the `reason` defined by the tool's `suspendSchema`. To continue the call, invoke `resumeStream` with the required `resumeSchema` and the `runId`.
+With this approach the stream includes a `tool-call-suspended` chunk, and the `suspendPayload` contains the `reason` defined by the tool's `suspendSchema`. Call `resumeStream` with the `resumeSchema` data and `runId` to continue:
 
 ```typescript
 const stream = await agent.stream("What's the weather in London?")
@@ -349,7 +379,7 @@ User: "San Francisco"
 Agent: "The weather in San Francisco is: San Francisco: ☀️ +72°F"
 ```
 
-The second message automatically resumes the suspended tool - the agent extracts `{ city: "San Francisco" }` from the user's message and passes it as `resumeData`.
+The second message automatically resumes the suspended tool, the agent extracts `{ city: "San Francisco" }` from the user's message and passes it as `resumeData`.
 
 ### Requirements
 
@@ -370,7 +400,7 @@ Both approaches work with the same tool definitions. Automatic resumption trigge
 
 ## Tool approval: Supervisor pattern
 
-The [supervisor pattern](https://mastra.ai/docs/agents/networks) lets a supervisor agent coordinate multiple subagents using `.stream()` or `.generate()`. The supervisor delegates tasks to subagents, which may use tools that require approval. When this happens, tool approvals properly propagate through the delegation chain -- the approval request surfaces at the supervisor level where you can handle it, regardless of which subagent triggered it.
+The [supervisor pattern](https://mastra.ai/docs/agents/networks) lets a supervisor agent coordinate multiple subagents using `.stream()` or `.generate()`. The supervisor delegates tasks to subagents, which may use tools that require approval. When this happens, tool approvals properly propagate through the delegation chain — the approval request surfaces at the supervisor level where you can handle it, regardless of which subagent triggered it.
 
 ### How it works
 
@@ -453,7 +483,7 @@ for await (const chunk of stream.fullStream) {
 
 ### Declining tool calls in supervisor pattern
 
-You can also decline tool calls at the supervisor level by calling `declineToolCall`. The supervisor will respond acknowledging the declined tool without executing it:
+Decline tool calls at the supervisor level by calling `declineToolCall`. The supervisor responds acknowledging the declined tool without executing it:
 
 ```typescript
 for await (const chunk of stream.fullStream) {
@@ -466,7 +496,7 @@ for await (const chunk of stream.fullStream) {
       toolCallId: chunk.payload.toolCallId,
     })
 
-    // The supervisor will respond acknowledging the declined tool
+    // The supervisor responds acknowledging the declined tool
     for await (const declineChunk of declineStream.textStream) {
       process.stdout.write(declineChunk)
     }
@@ -476,7 +506,7 @@ for await (const chunk of stream.fullStream) {
 
 ### Using suspend() in supervisor pattern
 
-Tools can also use [`suspend()`](#tool-approval-using-suspend) to pause execution and return context to the user. This approach works through the supervisor delegation chain the same way `requireApproval` does -- the suspension surfaces at the supervisor level:
+Tools can also use [`suspend()`](#approval-using-suspend) to pause execution and return context to the user. This approach works through the supervisor delegation chain the same way `requireApproval` does — the suspension surfaces at the supervisor level:
 
 ```typescript
 const conditionalTool = createTool({

package/.docs/docs/agents/supervisor-agents.md

@@ -192,7 +192,7 @@ const stream = await supervisor.stream('Research AI trends', {
 })
 ```
 
-Return `{ continue: true }` to keep iterating, or `{ continue: false }` to stop. Include optional `feedback` to add guidance that's visible to the next iteration.
+Return `{ continue: true }` to keep iterating, or `{ continue: false }` to stop. Include optional `feedback` to inject guidance into the conversation. When `feedback` is combined with `continue: false`, the model may get one final turn to produce a text response incorporating the feedback, but only if the current iteration is still active (e.g., after tool calls) — otherwise no extra turn is granted.
 
 ## Memory isolation
 

package/.docs/docs/getting-started/manual-install.md

@@ -1,6 +1,6 @@
 # Manual Install
 
-> **Info:** Use this guide to manually build a standalone Mastra server step by step. In most cases, it's quicker to follow a [getting-started guide](https://mastra.ai/docs/getting-started/start), which achieves the same result using the [`mastra create`](https://mastra.ai/reference/cli/create-mastra) command. For existing projects, you can also use [`mastra init`](https://mastra.ai/reference/cli/mastra).
+> **Info:** Use this guide to manually build a standalone Mastra server step by step. In most cases, it's quicker to follow the [quickstart guide](https://mastra.ai/guides/getting-started/quickstart), which achieves the same result using the [`mastra create`](https://mastra.ai/reference/cli/create-mastra) command. For existing projects, you can also use [`mastra init`](https://mastra.ai/reference/cli/mastra).
 
 If you prefer not to use our automatic CLI tool, you can set up your project yourself by following the guide below.
 

package/.docs/docs/index.md

@@ -1,43 +1,87 @@
-# About Mastra
+# Get Started
 
-Mastra is a framework for building AI-powered applications and agents with a modern TypeScript stack.
+Mastra is a TypeScript framework for building AI agents, workflows, and tools. Create your first project in seconds and start building.
 
-It includes everything you need to go from early prototypes to production-ready applications. Mastra integrates with frontend and backend frameworks like React, Next.js, and Node, or you can deploy it anywhere as a standalone server. It's the easiest way to build, tune, and scale reliable AI products.
+## Quickstart
 
-[YouTube video player](https://www.youtube-nocookie.com/embed/1qnmnRICX50)
+Run the command below to create a new Mastra project with an example agent:
 
-## Why Mastra?
+**npm**:
 
-Purpose-built for TypeScript and designed around established AI patterns, Mastra gives you everything you need to build great AI applications out-of-the-box.
+```bash
+npm create mastra@latest
+```
 
-Some highlights include:
+**pnpm**:
 
-- [**Model routing**](https://mastra.ai/models): Connect to 40+ providers through one standard interface. Use models from OpenAI, Anthropic, Gemini, and more.
+```bash
+pnpm create mastra
+```
 
-- [**Agents**](https://mastra.ai/docs/agents/overview): Build autonomous agents that use LLMs and tools to solve open-ended tasks. Agents reason about goals, decide which tools to use, and iterate internally until the model emits a final answer or an optional stopping condition is met.
+**Yarn**:
 
-- [**Workflows**](https://mastra.ai/docs/workflows/overview): When you need explicit control over execution, use Mastra's graph-based workflow engine to orchestrate complex multi-step processes. Mastra workflows use an intuitive syntax for control flow (`.then()`, `.branch()`, `.parallel()`).
+```bash
+yarn create mastra
+```
 
-- [**Human-in-the-loop**](https://mastra.ai/docs/workflows/suspend-and-resume): Suspend an agent or workflow and await user input or approval before resuming. Mastra uses storage to remember execution state, so you can pause indefinitely and resume where you left off.
+**Bun**:
 
-- **Context management**: Give your agents the right context at the right time. Provide [message history](https://mastra.ai/docs/memory/message-history), [retrieve](https://mastra.ai/docs/rag/overview) data from your sources (APIs, databases, files), and add human-like [working](https://mastra.ai/docs/memory/working-memory) and [semantic](https://mastra.ai/docs/memory/semantic-recall) memory so your agents behave coherently.
+```bash
+bunx create-mastra
+```
 
-- **Integrations**: Bundle agents and workflows into existing React, Next.js, or Node.js apps, or ship them as standalone endpoints. When building UIs, integrate with agentic libraries like Vercel's AI SDK UI and CopilotKit to bring your AI assistant to life on the web.
+This sets up a project you can test immediately in [Studio](https://mastra.ai/docs/getting-started/studio). See the [quickstart guide](https://mastra.ai/guides/getting-started/quickstart) for a full walkthrough.
 
-- **Production essentials**: Shipping reliable agents takes ongoing insight, evaluation, and iteration. With built-in [scorers](https://mastra.ai/docs/evals/overview) and [observability](https://mastra.ai/docs/observability/overview), Mastra gives you the tools to observe, measure, and refine continuously.
+## Integrate with your framework
 
-## What can you build?
+Add Mastra to an existing project or create a new app with your preferred framework.
 
-- AI-powered applications that combine language understanding, reasoning, and action to solve real-world tasks.
-- Conversational agents for customer support, onboarding, or internal queries.
-- Domain-specific copilots for coding, legal, finance, research, or creative work.
-- Workflow automations that trigger, route, and complete multi-step processes.
-- Decision-support tools that analyse data and provide actionable recommendations.
+- [Next.js](https://mastra.ai/guides/getting-started/next-js)
+- [React](https://mastra.ai/guides/getting-started/vite-react)
+- [Astro](https://mastra.ai/guides/getting-started/astro)
+- [Express](https://mastra.ai/guides/getting-started/express)
+- [SvelteKit](https://mastra.ai/guides/getting-started/sveltekit)
+- [Hono](https://mastra.ai/guides/getting-started/hono)
 
-## Get started
+For other frameworks, see the [framework integration guides](https://mastra.ai/guides/getting-started/next-js).
 
-Choose a [getting started guide](https://mastra.ai/docs/getting-started/start) to get started, or see the [manual installation guide](https://mastra.ai/docs/getting-started/manual-install) if you need more control over your setup.
+## What you can do
 
-If you're new to AI agents, check out our [templates](https://mastra.ai/templates), [course](https://mastra.ai/course), and [YouTube videos](https://youtube.com/@mastra-ai). You can also join our [Discord](https://discord.gg/BTYqqHKUrf) community to get help and share your projects.
+<details>
+**Conversational agents**
 
-We can't wait to see what you build ✌️
+Customer support, onboarding, or internal query bots. Agents maintain context across sessions with thread-based message history and observational memory — background agents that compress conversation history into dense observation logs, keeping the context window small while preserving long-term recall. Stream responses token-by-token for responsive chat UIs. Attach tools so agents can look up orders, create tickets, or call APIs mid-conversation.
+
+</details>
+
+<details>
+**Domain-specific copilots**
+
+Assistants for coding, legal, finance, research, or creative work. Ground agents in your own data with a full RAG pipeline — chunking, embedding, vector storage across 12+ providers, metadata filtering, and re-ranking. Customize behavior with dynamic instructions that adapt per user or request. Connect to external services through typed tools and MCP servers. Add voice interaction with 12+ speech providers, and measure output quality with built-in evaluation scorers.
+
+</details>
+
+<details>
+**Workflow automations**
+
+Multi-step processes that trigger, route, and complete tasks. Define type-safe steps with Zod-validated inputs and outputs, then compose them with sequential chaining, parallel fan-out, conditional branching, loops, and iteration with concurrency control. Suspend workflows mid-execution to wait for human approval or external events, then resume from where they left off. Nest workflows inside other workflows for reusable sub-pipelines.
+
+</details>
+
+<details>
+**Decision-support tools**
+
+Systems that analyze data and provide actionable recommendations. Compose multiple tools so agents can query databases, call APIs, and run analysis functions in a single interaction. Use structured output with Zod schemas to return validated, typed results. Coordinate specialist agents through supervisor patterns, with task-completion scoring to verify recommendation quality before finalizing. Add human-in-the-loop gates for high-stakes decisions.
+
+</details>
+
+<details>
+**AI-powered applications**
+
+Products that combine language understanding, reasoning, and action. Orchestrate multiple agents with supervisor delegation and multi-agent networks. Deploy to any Node.js runtime, cloud provider, or framework — Vercel, Cloudflare, Next.js, Astro, and more. Monitor production behavior with AI-specific tracing that captures token usage, latency, and decision paths. Choose from 10+ storage providers and configure composite backends optimized per workload. Test everything interactively in Studio before shipping.
+
+</details>
+
+Browse [templates](https://mastra.ai/templates) from Mastra and the community to see working examples of these use cases.
+
+[YouTube video player](https://www.youtube-nocookie.com/embed/1qnmnRICX50)

package/.docs/docs/mastra-cloud/setup.md

@@ -5,7 +5,7 @@ Import your Mastra project to [Mastra Cloud](https://cloud.mastra.ai) to use [St
 ## Before you begin
 
 - [Sign in](https://cloud.mastra.ai) to Cloud
-- Push your [Mastra project](https://mastra.ai/docs/getting-started/start) to GitHub
+- Push your [Mastra project](https://mastra.ai/docs) to GitHub
 
 ## Options
 

package/.docs/docs/memory/observational-memory.md

@@ -170,6 +170,15 @@ const memory = new Memory({
 })
 ```
 
+### Token counting cache
+
+OM caches tiktoken part estimates in message metadata to reduce repeat counting work during threshold checks and buffering decisions.
+
+- Per-part estimates are stored on `part.providerMetadata.mastra` and reused on subsequent passes when the cache version/tokenizer source matches.
+- For string-only message content (without parts), OM uses a message-level metadata fallback cache.
+- Message and conversation overhead are still recalculated on every pass. The cache only stores payload estimates, so counting semantics stay the same.
+- `data-*` and `reasoning` parts are still skipped and are not cached.
+
 ## Async Buffering
 
 Without async buffering, the Observer runs synchronously when the message threshold is reached — the agent pauses mid-conversation while the Observer LLM call completes. With async buffering (enabled by default), observations are pre-computed in the background as the conversation grows. When the threshold is hit, buffered observations activate instantly with no pause.

package/.docs/docs/memory/semantic-recall.md

@@ -147,8 +147,24 @@ Supported embedding models:
 
 - **OpenAI**: `text-embedding-3-small`, `text-embedding-3-large`, `text-embedding-ada-002`
 - **Google**: `gemini-embedding-001`
+- **OpenRouter**: Access embedding models from various providers
 
-The model router automatically handles API key detection from environment variables (`OPENAI_API_KEY`, `GOOGLE_GENERATIVE_AI_API_KEY`).
+```ts
+import { Agent } from '@mastra/core/agent'
+import { Memory } from '@mastra/memory'
+import { ModelRouterEmbeddingModel } from '@mastra/core/llm'
+
+const agent = new Agent({
+  memory: new Memory({
+    embedder: new ModelRouterEmbeddingModel({
+      providerId: 'openrouter',
+      modelId: 'openai/text-embedding-3-small',
+    }),
+  }),
+})
+```
+
+The model router automatically handles API key detection from environment variables (`OPENAI_API_KEY`, `GOOGLE_GENERATIVE_AI_API_KEY`, `OPENROUTER_API_KEY`).
 
 ### Using AI SDK Packages
 

package/.docs/docs/workspace/skills.md

@@ -117,13 +117,15 @@ const workspace = new Workspace({
 
 ## How agents use skills
 
-When an agent activates a skill, the skill's instructions are added to the conversation context. The agent can then follow those instructions and access the skill's references and scripts.
+When a workspace has skills configured, agents automatically get access to skill tools. Available skills are listed in the system message so the agent knows what's available, and the agent can load any skill on demand.
 
-Under the hood this involves:
+The agent has three skill tools:
 
-1. Lists available skills in the system message
-2. Allows agents to activate skills during conversation
-3. Provides access to skill references and scripts
+- **`skill`** — Loads a skill's full instructions and returns them in the tool result. The agent calls this whenever it needs a skill's guidance.
+- **`skill_read`** — Reads a file from a skill's `references/`, `scripts/`, or `assets/` directory.
+- **`skill_search`** — Searches across all skill content. Uses BM25 or vector search when configured, otherwise falls back to simple text matching.
+
+This design is stateless — there is no activation state to track. If the skill instructions leave the conversation context (due to context window limits or compaction), the agent can call `skill` again to reload them.
 
 ## Skill search