scanned Jun 3, 2026

Mastra

mastra.ai

Mastra is an open-source TypeScript framework for building AI-powered applications and agents.

70/100

Tier 4 · Agent-Ready

Content answers73/100
Protocol plumbing63/10010 of 16 checks pass

Scored by asking 15 questions a buyer of a ai-ml product asks, then grading this site’s own pages: answered, hedged (partial or vague), or silent (no page answers it). How scoring works

This report is public. Own mastra.ai? Claiming is free: crawl every page, re-audit as you fix, and track your score over time.

Sign in to claim

The fix queue

30 points sit between mastra.ai and 100: 7 open questions and 6 missing protocol checks, ordered by estimated payoff.

Point estimates are per fix under scoring v2. They are not additive to a promised total.

01migration · importance mediumGoes silent+7 content pts est.

We're migrating from LangChain. Does Mastra provide any migration path or compatibility wrapper for existing LangChain tool classes, or do I need to reimplement every tool using Mastra's native tool format?

What the pages say

No page on the site addresses this.

The fix

Add a dedicated migration guide or FAQ addressing LangChain adoption, specifically clarifying whether existing LangChain tool classes can be wrapped/reused or must be reimplemented using Mastra's native CreateTool format.

confidence high · grounding world-knowledge · weight 0.00 · Absent

02getting-started · importance lowGoes silent+7 content pts est.

When I run the Mastra CLI init command, can I pre-select a vector store like Pinecone or pgvector so the project scaffold is generated with the correct storage adapter wired up, or is that always manual setup after initialization?

What the pages say

No page on the site addresses this.

The fix

Document the Mastra CLI init command (e.g., `create-mastra` or `mastra init`) with its available flags or interactive prompts, specifically whether vector stores like Pinecone or pgvector can be pre-selected during scaffolding.

confidence high · grounding world-knowledge · weight 0.00 · Absent

Hedged · 5 of 15 questions

A buyer gets something, then has to guess the rest. Expand any row for the evidence and the fix.

03When routing LLM calls through the AI Gateway, is there a default request timeout or automatic retry policy configured out of the box, and can I override the maximum retry count per provider?limitsPage missing+2 pts est.

When routing LLM calls through the AI Gateway, is there a default request timeout or automatic retry policy configured out of the box, and can I override the maximum retry count per provider?

What the pages say

The retrieved chunks do not mention an “AI Gateway” specifically. Mastra’s top-level configuration sets a default per-task timeout of 300000 ms (5 minutes) via `defaultTimeoutMs`, which can be overridden per-tool or per-call [17]. The framework provides a default `RetryConfig` with configurable fields such as `maxRetries`, `retryDelayMs`, and `backoffMultiplier` [1][2][4][6], and automated retries are supported at the step or workflow level [6]. For model-specific retries, model fallbacks allow setting a retry count per fallback model [9]. The chunks do not specify default numeric values for `maxRetries`, nor do they document per-provider retry overrides in a gateway context.

The fix

Clarify in the configuration reference whether top-level timeout and retry settings apply to LLM provider calls, and document how (or if) users can override retry limits per provider or per model gateway route.

Where we looked: /reference/configuration, /reference/configuration, /reference/configuration, /blog/mastra-workflows-enhanced, /blog/model-fallback, /reference/configuration

confidence medium · grounding synthesized · weight 0.65 · Page missing

04Your agent memory guide mentions memory but doesn't specify retention limits. What is the default context window or message history cap before the agent starts summarizing or dropping earlier turns?limitsHedges+2 pts est.

Your agent memory guide mentions memory but doesn't specify retention limits. What is the default context window or message history cap before the agent starts summarizing or dropping earlier turns?

What the pages say

The chunks confirm that Mastra agents have a default memory configuration and that the `lastMessages` option controls how much recent conversation history is included per call, but they do not specify the default numeric value for `lastMessages` or a default context-window cap before the agent compresses or drops earlier turns. For long-running conversations, the docs note that raw message history grows until it fills the context window, and Observational Memory can be enabled to compress old messages automatically.

The fix

State the default value of `lastMessages` (and any other default memory limits) explicitly in the Memory Configuration Guide or Agent Memory API docs.

Where we looked: /blog/agent-memory-guide, /blog/agent-memory-guide, /learn/how-memory-works, /docs/memory/overview

confidence high · grounding synthesized · weight 0.70 · Vague

05In distributed or resumed workflow executions, does Mastra guarantee exactly-once semantics for step processing, or should I design my step functions to be idempotent to handle at-least-once delivery on retries?operationsHedges+2 pts est.

In distributed or resumed workflow executions, does Mastra guarantee exactly-once semantics for step processing, or should I design my step functions to be idempotent to handle at-least-once delivery on retries?

What the pages say

The retrieved chunks do not explicitly state whether Mastra guarantees exactly-once semantics for step processing in distributed or resumed executions. They document that Mastra supports automated retries at the step level when steps fail due to transient errors (for example, via `retryConfig` with `attempts` and `delay`), and that resumed workflows continue executing from where they last left off, but they do not specify whether steps may be executed more than once or whether step functions should be idempotent.

The fix

Document whether Mastra's workflow engine provides exactly-once, at-least-once, or best-effort execution semantics for steps, particularly in the context of retries and distributed execution. Include explicit guidance on idempotency requirements for step functions.

Where we looked: /blog/building-workflows, /ai-workflows, /blog/mastra-workflows-enhanced, /docs/workflows/error-handling, /docs/workflows/error-handling, /blog/introducing-temporal-workflows

confidence medium · grounding synthesized · weight 0.65 · Vague

06For complex AI workflows, is there a hard limit on the number of sequential steps a single workflow can execute, or a maximum runtime before the orchestration engine forces a timeout?limitsHedges+2 pts est.

For complex AI workflows, is there a hard limit on the number of sequential steps a single workflow can execute, or a maximum runtime before the orchestration engine forces a timeout?

What the pages say

The retrieved chunks do not specify a hard limit on the number of sequential steps a single Mastra workflow can execute, nor do they document a maximum runtime timeout enforced by the built-in orchestration engine. Mastra supports 'long-running workflows' with automatic state persistence and suspend/resume capabilities, and workflows can be deployed to external runners like Inngest that offer concurrency and rate-limiting controls, but no explicit step count or execution timeout ceiling is provided in the retrieved content.

The fix

Add a 'Limits and quotas' section to the workflow documentation that explicitly states whether there is a maximum number of sequential steps per workflow and any execution/runtime timeout enforced by the built-in orchestration engine.

Where we looked: /ai-workflows, /guides/deployment/inngest, /ai-agent-framework

confidence medium · grounding synthesized · weight 0.65 · Vague

07If I configure PostgreSQL as the agent memory backend, does Mastra manage its own connection pool, and what is the default pool size—or do I need to pass in an already-pooled client from my application?technicalHedges+2 pts est.

If I configure PostgreSQL as the agent memory backend, does Mastra manage its own connection pool, and what is the default pool size—or do I need to pass in an already-pooled client from my application?

What the pages say

The retrieved chunks show that Mastra supports PostgreSQL via `PostgresStore` using a `connectionString` (e.g., `postgresql://user:password@localhost:5432/myapp`), but they do not specify whether Mastra manages its own connection pool, what the default pool size is, or whether you must pass in an already-pooled client from your application.

The fix

Add documentation to the PostgreSQL storage reference explaining whether Mastra manages its own connection pool internally, the default pool size, and whether users should pass a pre-pooled client.

Where we looked: /blog/mastra-storage, /blog/mastra-storage, /blog/mastra-0.10

confidence medium · grounding synthesized · weight 0.65 · Vague

What the pages already answer cleanly

8 of 15. Answered with enough specificity for a buyer to act on. This is the bar the queue above is chasing.

deploymentAnswered

I need to keep all agent data in-house for compliance reasons. Does Mastra support fully self-hosted deployments on my own infrastructure, or is there a required SaaS control plane that processes agent telemetry?

What the pages say

Mastra supports fully self-hosted deployments on your own infrastructure and does not require a SaaS control plane. The framework is open-source under Apache 2.0 and lists self-hosted deployment as a core option alongside serverless and fully-managed paths. You can deploy Mastra Studio to your own production environment to manage agents, monitor performance, and inspect traces. Mastra Observability is offered as a hosted destination for agent telemetry, but connecting to it is optional and done by adding a platform exporter, indicating telemetry can remain in-house.

Source: /blog/choosing-a-js-agent-framework, mastra.ai, /ai-agent-framework, /workshops

confidence high · grounding synthesized · weight 0.95 · Answered

integrationAnswered

I keep seeing MCP mentioned alongside agents. Does Mastra include native Model Context Protocol support out of the box without installing extra adapters, or is it plugin-based?

What the pages say

Mastra includes native, first-party Model Context Protocol support rather than relying on external adapters. The framework provides `MCPClient` and `MCPServer` classes, supports `mcpServers` as a top-level configuration option, and server adapters automatically register MCP HTTP and SSE routes when configured. The `MCPServer` class is provided by Mastra's own `@mastra/mcp` package.

Source: /docs/mcp/overview, /reference/configuration, /docs/server/server-adapters, /reference/tools/mcp-server

confidence high · grounding synthesized · weight 0.95 · Answered

technicalAnswered

Can the AI Gateway dynamically fall back from one LLM provider to another based on specific HTTP error codes like 429 or 503, or is model routing strictly static based on the initial agent configuration?

What the pages say

Mastra supports dynamic fallback between models/providers based on runtime errors and does not rely strictly on static initial configuration. According to the model fallback documentation, when the primary model fails with a 500 error, rate limit, or timeout, the system automatically switches to the next configured fallback, and each model gets its own retry count before moving on. Additionally, Mastra supports runtime dynamic routing: the changelog shows that an agent’s `model` property can be a function that returns a fallback array dynamically based on `requestContext`. The chunks explicitly mention 500 errors and rate limits as automatic fallback triggers, but do not explicitly mention HTTP 503.

Source: /blog/model-fallback, /blog/changelog-2026-03-16

confidence high · grounding synthesized · weight 0.95 · Answered

legalAnswered

Before my legal team will approve usage, I need to know: is Mastra released under MIT, Apache 2.0, or another OSI-approved open-source license?

What the pages say

Mastra's core framework is released under the Apache License 2.0, a permissive open-source license. Enterprise features are separately licensed under the Mastra Enterprise License (source-available), not under Apache 2.0.

Source: /docs/community/licensing, mastra.ai, /terms-of-service

confidence high · grounding stated · weight 1.00 · Answered

observabilityAnswered

The observability page talks about evaluating agent performance. Are built-in eval metrics like toxicity scoring, exact-match, or LLM-as-a-judge included in the framework itself, or do I need to bring my own evaluation library?

What the pages say

Mastra includes these evaluation capabilities in its framework itself—you do not need to bring your own evaluation library. Toxicity scoring is available as a prebuilt scorer via `createToxicityScorer()` imported from `@mastra/evals/scorers/prebuilt`. LLM-as-a-judge is supported: Mastra’s blog notes it is adding LLM-as-judge metrics, and workshop transcripts describe both human and LLM judges as part of the framework. Deterministic, code-based checks (such as verifying string occurrence or factual data in outputs) are also supported natively.

Source: /reference/evals/toxicity, /reference/evals/toxicity, /blog/introducing-mastra-evals, /workshops/master-ai-evaluation-build-and-run-evals-with-mastra-2025-06-05, /docs/evals/overview, /docs/evals/built-in-scorers, /podcasts/evals-observability-agent-deployments-and-ai-news, /workshops/master-ai-evaluation-build-and-run-evals-with-mastra-2025-02-27

confidence high · grounding synthesized · weight 0.95 · Answered

observabilityAnswered

Are OpenTelemetry trace spans emitted automatically when I enable observability, or do I need to manually instantiate an OTLP exporter and configure batch span processing in my Mastra config file?

What the pages say

If you use Mastra's native OtelExporter, OpenTelemetry trace spans are emitted automatically when you add the exporter to your Mastra observability config; you do not need to manually instantiate an OTLP exporter or configure batch span processing in your Mastra config file, because the exporter internally handles BatchSpanProcessor. If you instead use the OtelBridge to integrate with an existing OpenTelemetry setup, you must manually instantiate an OTLP exporter and configure BatchSpanProcessor, but that is done in a separate instrumentation.ts file that runs before your application, not inside the Mastra config file itself.

Source: /docs/observability/tracing/exporters/otel, /docs/observability/tracing/bridges/otel, /docs/observability/tracing/bridges/otel, /docs/observability/tracing/bridges/otel

confidence high · grounding synthesized · weight 0.95 · Answered

observabilityAnswered

Does Mastra's observability stack integrate with third-party tracing platforms like Datadog, New Relic, or Honeycomb, or is monitoring limited to the framework's native dashboard?

What the pages say

Mastra integrates with third-party tracing platforms including Datadog and New Relic explicitly, and supports any OpenTelemetry-compatible platform generally. Monitoring is not limited to the framework's native dashboard. Mastra supports 'any OpenTelemetry-compatible platform, including MLflow, Langfuse, Braintrust, Datadog, New Relic and SigNoz.' Native options like Mastra Studio and Mastra Cloud are available alongside these third-party integrations via the DefaultExporter and CloudExporter.

Source: /ai-agent-observability, /ai-agent-observability

confidence high · grounding synthesized · weight 0.95 · Answered

Protocol plumbing · 63/10010 of 16 checks pass · each fix +6 protocol pts est.

The other half of the score: 16 checks for the files and headers agents look for. The 6 below are installs, not judgment calls, and most are an afternoon. Expand any for the snippet and the standard it follows. They sit after the queue because none of them changes what your pages say.

Content signalAccess+6 pts est.
Install snippet
User-agent: *
Content-Signal: search=yes, ai-input=yes, ai-train=no
Allow: /

StandardCloudflare proposalVendor proposal

Clean crawlAccess+6 pts est.

StandardSitedex metricSitedex metric

Markdown negotiationRendering+6 pts est.

StandardRFC 9110 + 7763IETF RFC

MCP cardInteraction+6 pts est.

Sitedex generates this file from your crawl. Grab it in Files from this audit below.

StandardModel Context ProtocolCommunity spec

OpenAPI specInteraction+6 pts est.

StandardOpenAPI SpecIndustry standard

WebMCP widgetInteraction+6 pts est.

Sitedex generates this file from your crawl. Grab it in Files from this audit below.

StandardW3C WebMCP draftW3C / WHATWG

Already passing 10 of 16: robots.txt, sitemap.xml, llms.txt, AI crawler access, Server-rendered content, Canonical URLs, Meta descriptions, HTML lang attribute, Organization schema, Sitemap lastmod.

Ask this site’s index

Sitedex already serves mastra.ai as an MCP endpoint. Ask mastra.ai anything an AI agent might ask, and see what its index returns. (To score your own site, use the form below.)

Snippets & configs

For developers and the engineer-on-call: copy these into your tools or your site.

Files from this audit

Built from this crawl. Download or copy each, then install it at the path noted.

llms.txt

Built from this crawl. Install at /llms.txt so agents start here.

organization.json

Organization JSON-LD, pre-filled from this crawl. Wrap in a ld+json script.

server-card.json

MCP server card built from this crawl. Host at /.well-known/mcp/server-card.json.

webmcp.json

WebMCP discovery manifest built from this crawl. Host at /.well-known/webmcp.json.

MCP endpoint

https://mcp.sitedex.dev/s/mastra-ai/mcp

The URL anyone's agent points at. Read-only; safe to share.

Claude Code

claude mcp add mastra --transport http https://mcp.sitedex.dev/s/mastra-ai/mcp

One command, then the agent has it.

Cursor / Continue

{
  "mcpServers": {
    "mastra": {
      "url": "https://mcp.sitedex.dev/s/mastra-ai/mcp"
    }
  }
}

Drop into mcp.json.

WebMCP: two parts

WebMCP-capable browsers run the widget at runtime. Crawlers without JS rendering need the discovery manifest to find your tool surface. Install both.

1 · Widget script

<script async src="https://sitedex.dev/widget.js"></script>

Drop in <head>. WebMCP-capable browsers (Chrome 146+ Origin Trial) call navigator.modelContext.provideContext() via this script.

2 · Discovery manifest

{
  "$schema": "https://wellknownmcp.org/schemas/webmcp.json",
  "name": "mastra.ai",
  "tools": [
    { "name": "search", "description": "Search mastra.ai's indexed content." },
    { "name": "get_page", "description": "Fetch a page from mastra.ai as markdown." }
  ]
}

Host alongside the script at /.well-known/webmcp.json. Crawlers that don't render JS rely on this.

Your turn

See which of these questions your site goes silent on.

Free, about 5 minutes. We crawl your site, test it against the buyer questions your category asks, and name what’s vague, contradictory, or missing, plus the files AI agents look for.

ComingEmbeddable grade badgeScore history and deltasOpt-in public board