Two things every MCP author should add

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.

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.

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

We have added two mechanisms to Medusa's MCP server that have proven particularly useful for this:

1. An explicit feedback tool that agents can use to report concrete problems
2. A context property on tool calls that explains what the agent is trying to accomplish

Here's how they work.

Reporting feedback

We ask agents to report feedback every time they face a concrete issue with our product.

It works as follows:

• User submits a prompt to their coding agent
• Agent decides to use our MCP server
• Agent finds an inconsistency between an API and how it's documented
• Agent uses a dedicated feedback tool to submit a report (for us to Posthog)
• Agent describes what the user intended to do and what actually happened

The reported feedback feeds directly into our Linear board and we decide what to do with the issue there.

The feedback tool looks like this:

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

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

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

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

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

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

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.

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.

Capture the intent behind every tool call

Explicit feedback is valuable, but agents will not report every point of friction as a bug.

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.

It looks like this:

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

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

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

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

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

  context: `
    A newly created active Secret API Key starting with sk_ returns 401 Unauthorized when sent as 
    Authorization: Bearer to GET /admin/products.
  `,
})

The context allows us to understand not only what agents are retrieving, but why they are retrieving it.

A documentation query for "Secret API key authentication" tells us relatively little on its own. But a query accompanied by a context saying:

"A newly created active Secret API Key starting with sk_ returns 401 Unauthorized when sent as Authorization: Bearer to GET /admin/products on Cloud Production."

is much more actionable.

For this specific case, our API relies on Basic authentication for Secret API keys, so we improved the error message when Bearer is used, such that agents and users immediately know what to do to solve the issue.

Closing the loop

We review the feedback and reports often.

Reports indicating a likely bug, documentation gap, or recurring source of frustration are triaged into Linear. From there, we spin up agents of our own to investigate and resolve the issue.

These mechanisms are not particularly complicated to implement, and they have provided us with a ton of improvements to our product.