Medusa is Good to agents.
Discry independently scored how well an AI agent can discover and understand the Medusa API from what’s public — not whether it’s usable. Below: every signal we checked, what’s costing the score, and what to change.
SCORED UNDER RUBRIC 1.2 · A full re-launch under Discry Score 2.5 — a new behavioral instrument, not comparable to these scores — is in progress.
Discovery
45% of score · 71/100Comprehension
55% of score · 91/100What we found
- An AI crawler trying to index Medusa's docs is blocked outright: the Cloudflare-managed robots.txt disallows GPTBot, ClaudeBot, Google-Extended, CCBot, Amazonbot and more, and sets Content-Signal ai-train=no — an ironic gap for one of the most deliberately AI-forward documentation sites assessed.
- Once an agent IS pointed at the docs, comprehension is excellent (91/A): every page exposes a 'View as Markdown' (.html.md) variant, a 26KB structured llms.txt and a 9,500-section llms-full.txt exist, and examples use realistic curl/JS SDK values (real-looking IDs, plausible product titles, working auth flows).
- Medusa ships first-class agent tooling: an official remote MCP server (listed on PulseMCP as an official provider and on Glama), a dedicated 'Build with AI Assistants and LLMs' docs chapter, a CLAUDE.md in the primary repo, and a separate medusa-agent-skills repo of Claude Code plugins.
- Discovery is held back by two mechanical failures beyond robots.txt: docs.medusajs.com/sitemap.xml returns HTTP 500 (and /sitemap-0.xml 404), and there is no /.well-known/mcp.json — so an agent cannot enumerate pages or auto-discover the MCP endpoint from the domain.
- The full Admin and Store APIs are OpenAPI-generated with a downloadable YAML spec, giving an agent a clean, importable contract — strong execution-documentation signal even though live behavior wasn't tested.
What to change
Prioritized by impact on discoverability. You (or your docs platform) deploy these — Discry never touches your API.
- 01Unblock AI agents in robots.txt: the Cloudflare-managed block of GPTBot/ClaudeBot/Google-Extended/CCBot directly contradicts Medusa's AI-friendly positioning. Allowing at least ai-input (RAG/grounding) crawlers would be the single highest-impact discovery fix.
- 02Fix the sitemap: docs.medusajs.com/sitemap.xml currently 500s. A working sitemap listing the /learn, /resources and /api pages lets agents enumerate the full surface instead of guessing URLs.
- 03Add a /.well-known/mcp.json pointing at the existing official remote MCP server so agents can auto-discover it from the domain rather than from a docs page.
- 04Add explicit error-recovery guidance to the API reference: pair each common error code (invalid_request_error, api_error, auth failures) with a concrete 'what to do next' step, so an agent can self-correct without trial-and-error.
- 05Publish a short 'API capabilities & boundaries' page covering what the REST API can/cannot do and where limits live (self-hosting note on rate limits, pagination caps), giving agents a single boundaries reference.
Execution coverage · INFORMATIONAL, UNSCORED
Whether an agent can actually complete a call and recover from errors is the deeper Audit layer — documented here, but not part of the Discry Score.
Medusa documents a consistent machine-parseable error object (type, message, snake_case code), session/bearer/api-key authentication, and offset-based pagination (limit/offset/count). Idempotency-Key is supported and shown in checkout/agentic-commerce flows. Rate limits are not documented because Medusa is self-hosted — the deploying team owns throttling, so an agent calling a Medusa instance cannot infer hosted limits from the docs.