@mastra/mcp-docs-server 1.1.5 → 1.1.6-alpha.0

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

@@ -0,0 +1,77 @@
+# Deployment
+
+Deploy your Mastra application to production and expose your agents, tools, and workflows as REST API endpoints.
+
+> **Info:** Mastra Cloud is currently in beta, but many teams are already using it to deploy their agents. It's the easiest way to run Mastra agents in a managed environment.
+
+## Enable deployments
+
+After [setting up your project](https://mastra.ai/docs/mastra-cloud/setup), click **Deployment** in the sidebar and select **Enable Deployments**.
+
+Once enabled, your project automatically builds and deploys. Future pushes to your main branch trigger automatic redeployments.
+
+## Dashboard
+
+The **Overview** page shows your project's domain URL, status, latest deployment, and connected agents and workflows.
+
+![Project dashboard](/assets/images/mastra-cloud-project-dashboard-6890c8032419d5fb075313d08bfd598b.jpg)
+
+Click the **Deployments** menu item to view build logs. Open **Settings** to configure environment variables, branch, storage, and endpoint URLs.
+
+> **Note:** Changes to settings require a new deployment to take effect
+
+## Storage configuration
+
+Mastra Cloud offers two storage options:
+
+1. **Mastra Cloud Store**: Managed storage provided by Mastra Cloud
+2. **Bring your own database**: Connect to your own external database
+
+### Using Mastra Cloud Store
+
+When using the managed Mastra Cloud Store (enabled in your project settings), storage must be configured on the `Mastra` instance, not on individual agent `Memory` instances.
+
+Configure storage on your Mastra instance:
+
+```typescript
+import { Mastra } from '@mastra/core'
+import { LibSQLStore } from '@mastra/libsql'
+
+export const mastra = new Mastra({
+  storage: new LibSQLStore({
+    id: 'mastra-store',
+    url: 'file:./mastra.db',
+  }),
+  agents: { myAgent },
+})
+```
+
+Agents can use Memory without specifying storage as they inherit from the Mastra instance:
+
+```typescript
+import { Agent } from '@mastra/core/agent'
+import { Memory } from '@mastra/memory'
+
+export const myAgent = new Agent({
+  id: 'my-agent',
+  memory: new Memory({
+    // No storage here - uses instance-level storage from Mastra Cloud Store
+    options: {
+      lastMessages: 20,
+    },
+  }),
+})
+```
+
+### Bring your own database
+
+If you don't use Mastra Cloud Store, you can use any [storage provider](https://mastra.ai/docs/memory/storage) with any configuration. Set your database connection strings as environment variables in your project's **Settings** page.
+
+## Using your deployment
+
+After deployment, interact with your agents using the [Mastra Client](https://mastra.ai/docs/server/mastra-client) or call the REST API endpoints directly.
+
+## Next steps
+
+- [Studio](https://mastra.ai/docs/mastra-cloud/studio) - Test your agents in the cloud
+- [Observability](https://mastra.ai/docs/mastra-cloud/observability) - Monitor traces and logs

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

@@ -0,0 +1,38 @@
+# Observability
+
+Cloud provides observability for production applications, giving you insight into how your agents and workflows behave. Observability works whether your application is deployed to Mastra Cloud, running locally, or hosted on your own infrastructure. Any Mastra project can send traces and logs to the platform regardless of where it's running.
+
+For details on configuring observability, see the [Cloud Exporter](https://mastra.ai/docs/observability/tracing/exporters/cloud) docs.
+
+## Traces
+
+Traces are available for both agents and workflows by enabling [observability](https://mastra.ai/docs/observability/tracing/overview) using one of the [supported providers](https://mastra.ai/docs/observability/tracing/overview).
+
+### Agents
+
+With observability enabled, you can view detailed outputs from your agents in the **Traces** section in [Studio](https://mastra.ai/docs/mastra-cloud/studio).
+
+![observability agents](/assets/images/mastra-cloud-observability-agents-a51e3bcac8589ba42fc5bd958a627187.jpg)
+
+Agent traces break a run into clear steps: model calls, tool calls, and intermediate chunks. Each includes timing, inputs, outputs, and errors. Drill into any span to inspect prompts, token usage, and results.
+
+### Workflows
+
+With observability enabled, you can view detailed outputs from your workflows in the **Traces** section in [Studio](https://mastra.ai/docs/mastra-cloud/studio).
+
+![observability workflows](/assets/images/mastra-cloud-observability-workflows-47baf49146575e665e3aad9f1fd65e5f.jpg)
+
+Workflow traces capture each step in the run, including transitions, branching, timing, and any tool calls. Inspect inputs, outputs, and errors for every step to debug long-running or multi-step processes.
+
+## Logs
+
+The **Logs** page in the [project dashboard](https://mastra.ai/docs/mastra-cloud/deployment) displays detailed information for debugging and monitoring your application's behavior.
+
+![Dashboard logs](/assets/images/mastra-cloud-dashboard-logs-85576fde4dda03bba2892bb6134a6ebf.jpg)
+
+Each log entry includes its severity level and a detailed message showing agent, workflow, or storage activity.
+
+## Next steps
+
+- [Logging](https://mastra.ai/docs/observability/logging)
+- [Tracing](https://mastra.ai/docs/observability/tracing/overview)

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

@@ -0,0 +1,23 @@
+# Mastra Cloud
+
+[Mastra Cloud](https://cloud.mastra.ai) is a platform for deploying, managing, and monitoring Mastra applications. [Import your project](https://mastra.ai/docs/mastra-cloud/setup) to get started.
+
+## Studio
+
+Run [Studio](https://mastra.ai/docs/mastra-cloud/studio) in the cloud and share access with your team via a link. Team members can test agents and workflows, tweak system prompts, and give feedback without running the project locally.
+
+## Deploy
+
+Enable [deployments](https://mastra.ai/docs/mastra-cloud/deployment) and Mastra Cloud hosts your server for you. Connect your GitHub repository for automatic deployments whenever you push to your configured branch. Mastra Cloud exposes your agents, tools, and workflows as REST API endpoints.
+
+Once deployed, the project dashboard gives you visibility into:
+
+- Deployment status and history
+- Build logs and configuration
+- Environment variables and settings
+
+## Observability
+
+[Observability](https://mastra.ai/docs/mastra-cloud/observability) provides insight into how your agents and workflows behave in production. View detailed traces of agent runs, workflow executions, and logs to debug issues and understand performance.
+
+> **Info:** You don’t need to deploy to Mastra Cloud to use Observability. You can send traces to Mastra from any environment

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

@@ -0,0 +1,42 @@
+# Setup
+
+Import your Mastra project to [Mastra Cloud](https://cloud.mastra.ai) to use [Studio](https://mastra.ai/docs/mastra-cloud/studio) and optionally [deploy](https://mastra.ai/docs/mastra-cloud/deployment) your agent.
+
+## Before you begin
+
+- [Sign in](https://cloud.mastra.ai) to Cloud
+- Push your [Mastra project](https://mastra.ai/docs/getting-started/start) to GitHub
+
+## Options
+
+![Select project type](/assets/images/mastra-cloud-select-6b31837ad5bcfb2be5f8085a524b576c.png)
+
+When you create a new project, you can choose from three options:
+
+1. **Create from GitHub** - Import a Mastra project from GitHub
+2. **Create from your server** - Connect a self-hosted Mastra instance to [Studio](https://mastra.ai/docs/mastra-cloud/studio)
+3. **Create from template** - Start from a [pre-built template](https://mastra.ai/templates)
+
+To create a project from GitHub, follow these steps:
+
+## Create from GitHub
+
+1. Connect to GitHub when prompted
+
+   ![Deployment details](/assets/images/mastra-cloud-connect-3d62fb8eb348f63097d77079610a6d90.png)
+
+2. Search for your repository and click **Import**
+
+   ![Deployment details](/assets/images/mastra-cloud-import-git-repository-bed773afbf510103f535451cbee5040f.jpg)
+
+3. Configure your project settings. Mastra Cloud auto-detects most settings, but you'll still need to enter the environment variables for your configured [model provider](https://mastra.ai/models):
+
+   ![Deployment details](/assets/images/mastra-cloud-deployment-details-e2c25f0d7d3ede4add9f8a907784c829.jpg)
+
+4. Click **Create Project**
+
+## Next steps
+
+Once your project is imported, [Studio](https://mastra.ai/docs/mastra-cloud/studio) automatically creates a sandbox where you can interact with your agents and share access with your team.
+
+When you're ready for production, enable [Deployment](https://mastra.ai/docs/mastra-cloud/deployment) settings and hit deploy!

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

@@ -0,0 +1,24 @@
+# Studio
+
+[YouTube video player](https://www.youtube-nocookie.com/embed/ojGu6Bi4wYk)
+
+Mastra Cloud provides a hosted version of [Studio](https://mastra.ai/docs/getting-started/studio) that gives your team a shared environment for interacting with and testing your agents. Team members can chat with agents, review traces, give feedback, and tweak system prompts - without needing to run the project locally.
+
+[Set up your project](https://mastra.ai/docs/mastra-cloud/setup) to access Studio in the cloud.
+
+See the [Studio documentation](https://mastra.ai/docs/getting-started/studio) for details on features like the Agents playground, Workflows runner, Tools testing, and MCP Servers.
+
+> **Note:** You don't need to deploy your agent to use Studio. Studio runs in a sandbox environment separate from your production deployment
+
+## Sharing access
+
+To invite team members, go to [Mastra Cloud](https://cloud.mastra.ai), click **Team Settings**, then **Members** to add them. Once invited, they can sign in and access your project's Studio.
+
+![Invite team members](/assets/images/mastra-cloud-invite-c91b5a0fff03de5ecba3e0162484c819.png)
+
+> **Warning:** Team members can view environment variables and delete projects. Only invite people you trust.
+
+## Next steps
+
+- [Deployment](https://mastra.ai/docs/mastra-cloud/deployment) - Manage deployments and settings
+- [Observability](https://mastra.ai/docs/mastra-cloud/observability) - Monitor traces and logs

package/.docs/docs/mastra-code/configuration.md

@@ -0,0 +1,299 @@
+# Configuration
+
+Mastra Code is configured through project-level files, global settings, and environment variables. Configuration files live in `.mastracode/` directories at the project and user levels.
+
+## Authentication
+
+Mastra Code supports two authentication methods: **API keys** (environment variables) and **OAuth** (provider subscriptions). You can use either or both.
+
+### API keys
+
+The simplest way to get started is to set API key environment variables for the providers you want to use. Mastra Code auto-detects these on startup:
+
+```sh
+export ANTHROPIC_API_KEY=sk-ant-...
+export OPENAI_API_KEY=sk-...
+export GOOGLE_GENERATIVE_AI_API_KEY=...
+export DEEPSEEK_API_KEY=...
+export CEREBRAS_API_KEY=...
+```
+
+Mastra Code uses Mastra's [model router](https://mastra.ai/models), which routes requests to the correct provider based on the model ID and available API keys. No OAuth login is required when using API keys.
+
+### OAuth login (optional)
+
+If you have an Anthropic Claude Max or OpenAI ChatGPT Plus subscription, you can authenticate via OAuth to use your subscription instead of API keys. Run `/login` in the TUI to start the flow.
+
+| Provider      | OAuth flow              | What you get                                  |
+| ------------- | ----------------------- | --------------------------------------------- |
+| **Anthropic** | Claude Max subscription | Access to Claude models via your subscription |
+| **OpenAI**    | ChatGPT Plus / Codex    | Access to OpenAI models via your subscription |
+
+OAuth credentials are stored in `auth.json` alongside the database in the [app data directory](#database-location). During onboarding, you can skip the OAuth step if you already have API keys configured.
+
+### Anthropic OAuth warning
+
+Authenticating with a Claude Max subscription through OAuth is a grey area. Anthropic has reportedly banned users for using Claude max credentials outside of Claude Code, so it may violate Anthropic Terms of Service.
+
+## MCP servers
+
+Mastra Code can connect to external [MCP](https://mastra.ai/docs/mcp/overview) servers and make their tools available to the agent. Configure servers in JSON files:
+
+| Priority | Path                          | Scope                            |
+| -------- | ----------------------------- | -------------------------------- |
+| Highest  | `.mastracode/mcp.json`        | Project                          |
+|          | `~/.mastracode/mcp.json`      | Global                           |
+| Lowest   | `.claude/settings.local.json` | Project (Claude Code compatible) |
+
+Project config overrides global config by server name. Claude Code settings are the lowest priority fallback.
+
+### MCP config format
+
+```json
+{
+  "mcpServers": {
+    "my-server": {
+      "command": "npx",
+      "args": ["-y", "@my-org/mcp-server"],
+      "env": {
+        "API_KEY": "your-key"
+      }
+    }
+  }
+}
+```
+
+Each server entry requires a `command` field. The `args` and `env` fields are optional.
+
+On startup, Mastra Code connects to all configured servers and reports the status:
+
+```text
+MCP: 2 server(s) connected, 15 tool(s)
+```
+
+Tools from MCP servers are namespaced as `serverName_toolName` and appear in the agent's tool list alongside built-in tools.
+
+## Hooks
+
+Hooks are user-configured shell commands that run at specific lifecycle events. Use hooks for custom validation, logging, notifications, or integration with external systems.
+
+### Hook config format
+
+```json
+{
+  "PreToolUse": [
+    {
+      "type": "command",
+      "command": "node scripts/validate-tool.js",
+      "matcher": {
+        "tool_name": "execute_command"
+      },
+      "timeout": 5000,
+      "description": "Validate shell commands before execution"
+    }
+  ],
+  "PostToolUse": [
+    {
+      "type": "command",
+      "command": "node scripts/log-tool.js",
+      "description": "Log tool usage"
+    }
+  ]
+}
+```
+
+### Hook events
+
+| Event              | When it fires                                                   | Can block? |
+| ------------------ | --------------------------------------------------------------- | ---------- |
+| `PreToolUse`       | Before a tool call executes                                     | Yes        |
+| `PostToolUse`      | After a tool call completes                                     | No         |
+| `Stop`             | When an agent response ends (`complete`, `aborted`, or `error`) | Yes        |
+| `UserPromptSubmit` | When the user sends a message                                   | Yes        |
+| `SessionStart`     | When a session begins                                           | No         |
+| `SessionEnd`       | When a session ends                                             | No         |
+| `Notification`     | When the TUI fires a notification                               | No         |
+
+`UserPromptSubmit` runs before a non-command prompt is sent to the agent. If a hook blocks, the prompt is not sent.
+
+### Hook I/O protocol
+
+Hook processes receive a JSON payload on stdin with context about the event:
+
+```json
+{
+  "session_id": "thread-abc123",
+  "cwd": "/path/to/project",
+  "hook_event_name": "PreToolUse",
+  "tool_name": "execute_command",
+  "tool_input": { "command": "npm test" }
+}
+```
+
+For blocking events (`PreToolUse`, `Stop`, `UserPromptSubmit`), the hook can respond on stdout with a JSON object:
+
+```json
+{
+  "decision": "block",
+  "reason": "This command is not allowed"
+}
+```
+
+### Hook config locations
+
+| Priority | Path                       | Scope                           |
+| -------- | -------------------------- | ------------------------------- |
+| Higher   | `.mastracode/hooks.json`   | Project (appended after global) |
+| Lower    | `~/.mastracode/hooks.json` | Global (runs first)             |
+
+Global hooks run before project hooks. For the same event, all hooks execute in order.
+
+## Custom slash commands
+
+Define reusable prompt templates as markdown files. Mastra Code scans these directories for `.md` files:
+
+| Priority | Path                      | Scope                            |
+| -------- | ------------------------- | -------------------------------- |
+| Highest  | `.mastracode/commands/`   | Project                          |
+|          | `.claude/commands/`       | Project (Claude Code compatible) |
+|          | `~/.mastracode/commands/` | Global                           |
+| Lowest   | `~/.claude/commands/`     | Global (Claude Code compatible)  |
+
+Each command file can include YAML frontmatter with `name` and `description` fields:
+
+```yaml
+---
+name: review
+description: Review the current diff for issues
+---
+Review my current git diff. Look for bugs, security issues,
+and violations of the project's coding standards.
+```
+
+The filename (or directory structure) determines the command name. For example, `git/commit.md` becomes `/git:commit`.
+
+Commands support variables like `$ARGUMENTS` for positional args, `@filename` for file content injection, and `!command` for shell command output.
+
+## Skills
+
+Skills are structured instruction files that the agent loads automatically based on trigger conditions. They provide domain-specific guidance without manually pasting instructions.
+
+Mastra Code scans these directories for skills:
+
+| Priority | Path                    | Scope                            |
+| -------- | ----------------------- | -------------------------------- |
+| Highest  | `.mastracode/skills/`   | Project                          |
+|          | `.claude/skills/`       | Project (Claude Code compatible) |
+|          | `~/.mastracode/skills/` | Global                           |
+| Lowest   | `~/.claude/skills/`     | Global (Claude Code compatible)  |
+
+Each skill is a directory containing a `SKILL.md` file with instructions and trigger descriptions. Skills installed via symlinks (e.g., from `npx skills add`) are automatically resolved.
+
+## Agent instructions
+
+Mastra Code loads project-specific instructions from `AGENTS.md` or `CLAUDE.md` files and injects them into the agent's system prompt. This is how you can customize the agent's behavior for your project.
+
+### Lookup order
+
+For project instructions (first match wins):
+
+1. `AGENTS.md` or `CLAUDE.md` in the project root
+2. `.claude/AGENTS.md` or `.claude/CLAUDE.md`
+3. `.mastracode/AGENTS.md` or `.mastracode/CLAUDE.md`
+
+For global instructions (first match wins):
+
+1. `~/.claude/AGENTS.md` or `~/.claude/CLAUDE.md`
+2. `~/.mastracode/AGENTS.md` or `~/.mastracode/CLAUDE.md`
+3. `~/.config/claude/AGENTS.md` or `~/.config/claude/CLAUDE.md`
+4. `~/.config/mastracode/AGENTS.md` or `~/.config/mastracode/CLAUDE.md`
+
+`AGENTS.md` takes priority over `CLAUDE.md` when both exist at the same location.
+
+## Storage
+
+Mastra Code stores threads, messages, state, and observational memory in a database. It uses LibSQL by default with a local file — no setup needed.
+
+To switch to a remote LibSQL (Turso) or PostgreSQL backend, run `/settings` and select a storage backend. You'll be prompted for a connection URL.
+
+If a PostgreSQL connection fails on startup, Mastra Code falls back to LibSQL and shows a warning so you can fix the connection via `/settings`.
+
+## Observational memory
+
+[Observational memory](https://mastra.ai/docs/memory/observational-memory) (OM) uses background agents to maintain a dense log of observations and reflections about the conversation, providing long-term context that persists across sessions.
+
+### OM scope
+
+Control whether observations are scoped to individual threads or shared across all threads for a project:
+
+| Scope              | Behavior                                                        |
+| ------------------ | --------------------------------------------------------------- |
+| `thread` (default) | Observations are private to each conversation thread            |
+| `resource`         | Observations are shared across all threads for the same project |
+
+Configure the scope through:
+
+1. `MASTRA_OM_SCOPE` environment variable (`"thread"` or `"resource"`)
+2. `.mastracode/database.json` → `omScope` field
+3. `~/.mastracode/database.json` → `omScope` field
+
+### OM model settings
+
+The observer and reflector models default to `google/gemini-2.5-flash`. Override them per-thread through the `/settings` panel or in the harness state.
+
+### OM thresholds
+
+| Threshold             | Default       | Description                                   |
+| --------------------- | ------------- | --------------------------------------------- |
+| Observation threshold | 30,000 tokens | Token count that triggers an observation pass |
+| Reflection threshold  | 40,000 tokens | Token count that triggers a reflection pass   |
+
+## Color theme
+
+Mastra Code detects your terminal's color scheme and applies a matching dark or light theme. You can override the detected theme with the `/theme` slash command or the `MASTRA_THEME` environment variable.
+
+### Detection order
+
+1. `MASTRA_THEME` environment variable — explicit `dark` or `light`
+2. Persisted setting from `/theme` command (stored in `settings.json`)
+3. OSC 11 query — asks your terminal for its actual background color
+4. `COLORFGBG` environment variable (set by some terminals like iTerm2 and Konsole)
+5. Falls back to dark theme
+
+### Switching themes
+
+Use the `/theme` command to change the theme at runtime:
+
+```text
+/theme light
+/theme dark
+/theme auto
+```
+
+Running `/theme` with no arguments shows the current theme. The choice is persisted across sessions.
+
+## Environment variables
+
+| Variable               | Description                                                    |
+| ---------------------- | -------------------------------------------------------------- |
+| `MASTRA_DB_URL`        | LibSQL database URL (e.g., `libsql://...` or `file:./data.db`) |
+| `MASTRA_DB_AUTH_TOKEN` | Auth token for remote LibSQL database                          |
+| `MASTRA_DB_PATH`       | Override the local database file path                          |
+| `MASTRA_USER_ID`       | Override the auto-detected user identity                       |
+| `MASTRA_RESOURCE_ID`   | Override the auto-detected project resource ID                 |
+| `MASTRA_OM_SCOPE`      | Observational memory scope (`thread` or `resource`)            |
+| `DEFAULT_OM_MODEL_ID`  | Default model for OM observer and reflector                    |
+| `MASTRA_THEME`         | Color theme override (`dark` or `light`)                       |
+| `TAVILY_API_KEY`       | Enable Tavily-powered web search and extract tools             |
+
+## Resource ID override
+
+Resource IDs determine how threads are grouped. By default, Mastra Code generates one from the Git remote URL or filesystem path. Override it to share threads across repositories or isolate threads within a monorepo:
+
+```json
+{
+  "resourceId": "my-custom-project-id"
+}
+```
+
+You can also set `MASTRA_RESOURCE_ID` as an environment variable. Two users who set the same resource ID share threads and observations for that resource.