Mastra Framework Guide
When NOT to use
- mdeAI product intent routing (rentals vs events) →
src/mastra/agents/concierge.ts + PRD; archived mastra-routing skill is not scanned
- Anthropic Managed Agents cloud harness →
mde-agents (.agents/skills/)
- Generic “build an agent” with no Mastra imports →
mde-agents or product docs, not framework internals here
- CopilotKit v2 (
useComponent, slots, headless v2) → defer for mdeapp; use copilotkit-integrations + references/copilotkit.md only for separate-server pattern
Build AI applications with Mastra. This skill teaches you how to find current documentation and build agents and workflows.
Event discovery ingest (plans 10–11)
Mastra orchestrates batch ingest; searchEventsTool queries approved events only. Verify APIs via Mastra docs MCP before new workflow steps.
⚠️ Critical: Do not trust internal knowledge
Everything you know about Mastra is likely outdated or wrong. Never rely on memory. Always verify against current documentation.
Your training data contains obsolete APIs, deprecated patterns, and incorrect usage. Mastra evolves rapidly - APIs change between versions, constructor signatures shift, and patterns get refactored.
Prerequisites
Before writing any Mastra code, check if packages are installed:
ls node_modules/@mastra/
- If packages exist: Use embedded docs first (most reliable)
- If no packages: Install first or use remote docs
Available files
Bookmark index: links.md — official mastra.ai doc URLs + local reference map (start here for “where is the doc for X?”). Includes web search tutorial URL, upstream GitHub issues, and skill maintenance (.agents/skills/skill-creator/SKILL.md).
Reference index: references/README.md — every references/*.md file has YAML frontmatter (title, description, parent: mastra). Load one ref per task.
Topic routing: references/topic-routing.md — maps tasks (agents, workflows, MCP, deployment, …) to the right links.md section and optional local references/*.md files.
Mastra docs MCP
Cursor: user-mastra server — see references/mcp-docs-lookup.md.
| Tool | Use when |
|---|
mastraDocs | You know the doc path (docs/..., guides/..., reference/...) |
readMastraDocs | Browse embedded topics in installed @mastra/* packages |
searchMastraDocs | Keyword grep in embedded docs — requires projectPath: /home/sk/mdeai/mdeapp |
listMastraPackages | See which packages ship embedded docs |
Codex / stdio (optional):
codex mcp add mastra-docs -- npx -y @mastra/mcp-docs-server@latest
codex mcp list
Use mastra-docs when embedded package docs are missing or sparse and you need official, current Mastra documentation. For application code that connects an agent to external MCP tools, follow the official MCP overview: https://mastra.ai/docs/mcp/overview#using-mcpclient-with-an-agent.
Key pattern:
import { MCPClient } from '@mastra/mcp'
import { Agent } from '@mastra/core/agent'
export const docsMcpClient = new MCPClient({
id: 'docs-mcp-client',
servers: {
mastraDocs: {
command: 'npx',
args: ['-y', '@mastra/mcp-docs-server@latest'],
},
},
})
export const docsAgent = new Agent({
id: 'docs-agent',
name: 'Docs Agent',
instructions: 'Use the Mastra docs MCP server for current Mastra documentation.',
model: 'openai/gpt-5.4',
tools: await docsMcpClient.listTools(),
})
References
| User Question | First Check | How To |
|---|
| "Where is the doc for topic X?" | links.md and references/topic-routing.md | URL tables + intent → section + local refs |
| "Create/install Mastra project" | references/create-mastra.md | Setup guide with CLI and manual steps |
| "How do I use Agent/Workflow/Tool?" | references/embedded-docs.md | Look up in node_modules/@mastra/*/dist/docs/ |
| Memory (docs + reference API) | references/memory.md | Working memory, OM, threads, storage |
| Workflows (docs + reference API) | references/workflows.md | Suspend/resume, snapshots, Roberto HITL |
| Streaming (docs + reference API) | references/streaming.md | AG-UI bridge, tool-call events, context.writer |
| Browser (docs + reference API) | references/browser.md | AgentBrowser, BrowserViewer, Stagehand — Phase 2 / EVP |
| Examples v0 + guides (Supatabs) | references/examples-v0.md | WM schema, calling agents, WhatsApp, Inngest |
| "How do I use MCPClient or MCPServer?" | links.md and references/mcp-docs-lookup.md | Official MCP docs + Cursor mastraDocs / readMastraDocs |
| "How do I use X?" (no packages) | references/remote-docs.md | Fetch from https://mastra.ai/llms.txt |
Scripts
scripts/provider-registry.mjs: Look up current providers and models available in the model router. Always run this before using a model to verify provider keys and model names.
Priority order for writing code
⚠️ Never write code without checking current docs first.
-
Embedded docs first (if packages installed)
Look up current docs in node_modules for a package. Example of looking up "Agent" docs in @mastra/core:
grep -r "Agent" node_modules/@mastra/core/dist/docs/references
-
Source code second (if packages installed)
If you can't find what you need in the embedded docs, look directly at the source code. This is more time consuming but can provide insights into implementation details.
cat node_modules/@mastra/core/dist/docs/assets/SOURCE_MAP.json | grep '"Agent"'
cat node_modules/@mastra/core/dist/[path-from-source-map]
- Why: Ultimate source of truth if docs are missing or unclear
- Use when: Embedded docs don't cover your question
- More information:
references/embedded-docs.md
-
Remote docs third (if packages not installed)
You can fetch the latest docs from the Mastra website:
https://mastra.ai/llms.txt
- Why: Latest published docs (may be ahead of installed version)
- Use when: Packages not installed or exploring new features
- More information:
references/remote-docs.md
Core concepts
Agents vs workflows
Agent: Autonomous, makes decisions, uses tools
Use for: Open-ended tasks (support, research, analysis)
Workflow: Structured sequence of steps — see references/workflows.md for suspend/resume (Roberto HITL W3+)
Key components
- Tools: Extend agent capabilities (APIs, databases, external services)
- Memory: Message history, working memory, observational memory, semantic recall — see
references/memory.md
- RAG: Query external knowledge (vector stores, graph relationships)
- Storage: Persist data (Postgres, LibSQL, MongoDB)
Mastra Studio
Studio provides an interactive UI for building, testing, and managing agents, workflows, and tools. It helps with debugging and improving your applications iteratively.
Inside a Mastra project, run:
npm run dev
Then open http://localhost:4111 in your browser to access Mastra Studio.
Critical requirements
TypeScript config
Mastra requires ES2022 modules. CommonJS will fail.
{
"compilerOptions": {
"target": "ES2022",
"module": "ES2022",
"moduleResolution": "bundler"
}
}
Model format
Always use "provider/model-name" when defining models using Mastra's model router.
Use the provider registry script to look up available providers and models:
node scripts/provider-registry.mjs --list
node scripts/provider-registry.mjs --provider openai
node scripts/provider-registry.mjs --provider anthropic
When the user asks to use a model or provider, always run the script first to verify the provider key and model name are valid. Do not guess model names from memory as they change frequently.
Example model strings:
"openai/gpt-5.4""anthropic/claude-sonnet-4-5""google/gemini-2.5-pro"
When you see errors
Type errors often mean your knowledge is outdated.
Common signs of outdated knowledge:
Property X does not exist on type YCannot find moduleType mismatch errors- Constructor parameter errors
What to do:
- Check
references/common-errors.md
- Verify current API in embedded docs
- Don't assume the error is a user mistake - it might be your outdated knowledge
Development workflow
Always verify before writing code:
-
Check packages installed
ls node_modules/@mastra/
-
Look up current API
-
Write code based on current docs
-
Test in Studio
npm run dev
Resources
