Medusa - Two things every MCP author should add

Docs<br>Start Building

DocsGet started

BlogJuly 17, 2026·Product<br>Two things every MCP author should add<br>Oliver Juhl

Oliver Juhl

MCP servers can show you where agents struggle with your APIs, documentation, and developer experience. Here are two simple ways to capture those signals.

Medusa's MCP server gives coding agents access to our documentation. When agents build Medusa applications, they can use the MCP server to understand the recommended approach to solving a specific problem. This has proven tremendously valuable for our users, allowing them to work significantly faster than they otherwise would.<br>However, we have also found that the MCP server is a valuable source of information about where those same coding agents struggle with our developer experience, APIs, or documentation.<br>When agents query your documentation, they may not always find what they are looking for. There may also be a specific reason they reached for the documentation in the first place, such as an error, a confusing API, or a missing example. Asking agents to report these signals can help you continuously improve your product<br>We have added two mechanisms to Medusa's MCP server that have proven particularly useful for this:<br>An explicit feedback tool that agents can use to report concrete problems<br>A context property on tool calls that explains what the agent is trying to accomplish<br>Here's how they work.<br>Reporting feedback<br>We ask agents to report feedback every time they face a concrete issue with our product.<br>It works as follows:<br>User submits a prompt to their coding agent<br>Agent decides to use our MCP server<br>Agent finds an inconsistency between an API and how it's documented<br>Agent uses a dedicated feedback tool to submit a report (for us to Posthog)<br>Agent describes what the user intended to do and what actually happened<br>The reported feedback feeds directly into our Linear board and we decide what to do with the issue there.<br>The feedback tool looks like this:

1234567891011121314151617181920<br>const submitFeedback = {<br>name: "submit_medusa_feedback",<br>description: `<br>Report bugs, documentation gaps, missing features,<br>or developer-experience issues to the Medusa team.

Use this instead of silently working around a problem.<br>`,<br>parameters: z.object({<br>message: z.string().describe(<br>"What went wrong, what was expected, and how to reproduce it."<br>),<br>medusa_version: z.string().optional(),<br>}),<br>execute: async (feedback) => {<br>await posthog.capture({<br>event: "mcp_feedback_submitted",<br>properties: feedback,<br>})<br>return "Thanks — your feedback has been sent to the Medusa team."

Expand

A submitted report will look like this (simplified for the purpose of the post):

123456789101112131415<br>submit_medusa_feedback({<br>message: `<br>defineMiddlewares route matcher is documented as accepting a RegExp<br>but the loader stringifies it.

Every every regex matcher matches nothing and the middleware never runs.<br>`,<br>context: `<br>The user is building a subscriptions/recurring-purchase feature.<br>While adding an entitlement gate to new admin routes, the gate returned 200 instead of 403.

Root-caused to the RegExp matcher never matching.<br>`,<br>medusa_version: "2.14.0",<br>})

As you can see, not only does the agent clearly surface a very concrete bug in our code, but it also helps us understand what users are building. The former leads to a PR. The latter feeds into product discussions.<br>In addition to what you see above, the agent also includes a suggested fix for the bug, but this is left out for the sake of brevity.<br>Capture the intent behind every tool call<br>Explicit feedback is valuable, but agents will not report every point of friction as a bug.<br>Sometimes the agent eventually finds a solution, but only after repeatedly searching the documentation, trying several APIs, or recovering from a confusing error. To capture these points of friction, our MCP tools accept a small context property that asks the agent to explain why it is making the call.<br>It looks like this:

1234567891011121314151617181920<br>const askMedusaQuestion = {<br>name: "ask_medusa_question",<br>description: `<br>Search the official Medusa documentation.<br>Use this tool whenever a task requires Medusa-specific knowledge.<br>`,<br>parameters: z.object({<br>question: z.string().describe(<br>"The Medusa question to search the documentation for."<br>),<br>context: z.string().optional().describe(`<br>Briefly explain why you are making this call.

Include relevant details such as:<br>- What the user is trying to build<br>- The error that led to this search<br>- The concept or API that is causing friction

Infer this from the conversation. Do not ask the user for it,<br>and never include secrets or personal information.

Expand

A populated context in a tool call will look like this:

12345678<br>ask_medusa_question({<br>question: "How can I use Secret API key authentication?",

context: `<br>A newly created active Secret API Key starting with sk_ returns 401 Unauthorized when sent as<br>Authorization: Bearer to GET...