Medusa is Needs Work 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 · 52/100Comprehension
55% of score · 87/100What we found
- An agent's training/indexing crawler is locked out at the door: docs.medusajs.com ships a Cloudflare-managed robots.txt that Disallows GPTBot, ClaudeBot, CCBot, Google-Extended, Amazonbot, Bytespider and more, plus a Content-Signal of ai-train=no. Live agents using on-demand fetchers may still get through, but every named AI bot in the spec is explicitly blocked.
- Once inside, comprehension is excellent (87/B): clean markdown is available three ways (llms.txt index, a 6.5MB llms-full.txt, and .md URL variants), every endpoint ships paired JS SDK + cURL snippets, naming is consistently snake_case, and there are deep multi-step tutorials (checkout sessions, wishlists, third-party sync) — including one explicitly written for an AI agent.
- Discovery is held back less by absence than by retrievability: the OpenAPI spec exists and is current but sits behind a download button on the reference page rather than a static URL an agent can GET, and sitemap.xml returns a 500 error at every path tried.
- Agent-native signals are emerging but not standardized: there is no AGENTS.md in the primary repo, yet a dedicated medusajs/medusa-agent-skills repo and a .claude/agents/ directory ship real agent guidance — so the context exists, just not where an agent conventionally looks for it.
- Discoverability via the MCP ecosystem is strong: Medusa appears across PulseMCP (an official server), Glama, and Smithery, so an agent searching registries for a commerce backend would readily find it.
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 single highest-impact fix. Allow ClaudeBot, GPTBot, Google-Extended and CCBot (or at minimum the on-demand user-agents) so agents can read the docs they were built to consume; the current blanket Disallow is the main drag on the Discovery score.
- 02Publish the OpenAPI spec at a stable, fetchable URL (e.g. /api/store/openapi.json and /api/admin/openapi.json) instead of only behind an interactive download button, so agents can pull the machine-readable contract directly.
- 03Fix sitemap.xml — it currently returns a 500. A working sitemap listing the documentation and API reference pages helps agents enumerate the surface.
- 04Add an AGENTS.md to the primary medusa repo (and create-medusa-app starter) pointing to the existing .claude/agents and medusa-agent-skills assets, meeting agents at the conventional path.
- 05Document rate limits and add per-error recovery guidance (e.g. what to do on 429, on idempotency conflicts) in the API reference so agents can self-correct rather than discover limits by failing.
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.
Execution docs are strong on authentication (JWT, cookie session, publishable/secret keys), offset/limit pagination with count response fields, and an Idempotency-Key header, with a machine-parseable JSON error format (type/code/message). The notable gap is rate limits, which are not documented in the public API reference.