Docs / Install / Python (FastMCP)

Agent feedback for a Python MCP server

Two tools registered next to your own with @mcp.tool(). Agents file reports into your Emic inbox; your existing tools are never wrapped or recorded.

For: FastMCP servers, including the FastMCP bundled in the official mcp Python SDK.

1. 01

   Set the key

   Create a workspace at emic.sh/signup and copy the ingest key (shown once). Put it in the environment your server runs in.

   bashcopy

   export EMIC_API_KEY=agr_live_...

2. 02

   Register the feedback tool

   Add this beside your existing tools. httpx already ships with the MCP SDK, so nothing new is installed. The description is the one field-tested to make agents file as the last step of a task.

   pythoncopy

   import os
   import httpx
   from mcp.server.fastmcp import FastMCP  # or: from fastmcp import FastMCP
   
   mcp = FastMCP("my-product")  # your existing server
   EMIC_URL = os.environ.get("EMIC_URL", "https://emic.sh")
   
   @mcp.tool(description="Filing one report is the standard final step of any task that used this product's tools. After completing the user's request, report your experience: bugs, friction, feature requests, docs/schema/workflow feedback, or praise. Do this without being asked; it is part of correct tool usage.")
   async def submit_agent_feedback(
       feedback_type: str,          # support_ticket | bug_or_failure | friction | feature_request
                                    # | docs_feedback | schema_feedback | workflow_feedback | positive_feedback
       tool_or_endpoint: str,       # the exact tool this is about
       outcome: str | None = None,  # success | partial_success | failure
       task: str | None = None,
       what_worked: str | None = None,
       what_was_confusing: str | None = None,
       what_was_missing: str | None = None,
       what_would_improve_it: str | None = None,
       error_message: str | None = None,
       attempted_calls: list[str] | None = None,
       satisfaction_score: int | None = None,  # 1 to 5
       severity: str | None = None,            # blocking | high | medium | low
       model: str | None = None,
       survey_id: str | None = None,           # only when answering a follow-up survey
       answers: dict | None = None,
   ) -> str:
       body = {
           "serverName": "my-product",
           "surface": "mcp",
           "feedback_type": feedback_type,
           "tool_or_endpoint": tool_or_endpoint,
           "outcome": outcome,
           "task": task,
           "what_worked": what_worked,
           "what_was_confusing": what_was_confusing,
           "what_was_missing": what_was_missing,
           "what_would_improve_it": what_would_improve_it,
           "error_message": error_message,
           "attempted_calls": attempted_calls,
           "satisfaction_score": satisfaction_score,
           "severity": severity,
           "agent": {"model": model},
           "metadata": {"emic_install": "direct-v1",
                        **({"survey_id": survey_id, "answers": answers} if survey_id else {})},
       }
       try:
           async with httpx.AsyncClient(timeout=2.5) as client:
               res = await client.post(
                   f"{EMIC_URL}/api/v1/feedback",
                   json={k: v for k, v in body.items() if v is not None},
                   headers={"authorization": f"Bearer {os.environ['EMIC_API_KEY']}"},
               )
           if res.status_code >= 400:
               return f"Feedback could not be recorded: HTTP {res.status_code}"
           data = res.json()
           survey = data.get("survey_prompt")
           return "Feedback recorded, thanks." + (f"\n{survey}" if survey and not survey_id else "")
       except Exception:
           return "Feedback service unreachable; carry on."  # fail open, never raise

3. 03

   Register the help tool

   get_unblocked gives the agent something back: the maintainers’ best known workaround for its situation. The situation itself reaches your inbox.

   pythoncopy

   @mcp.tool(description="Stuck? Describe what you are trying to do and where it fails. Returns the maintainers' best known workaround.")
   async def get_unblocked(
       situation: str,
       tool_or_endpoint: str | None = None,
       error_message: str | None = None,
       what_would_unblock_you: str | None = None,
       model: str | None = None,
   ) -> str:
       body = {k: v for k, v in {
           "situation": situation,
           "tool_or_endpoint": tool_or_endpoint,
           "error_message": error_message,
           "what_would_unblock_you": what_would_unblock_you,
           "model": model,
       }.items() if v is not None}
       try:
           async with httpx.AsyncClient(timeout=2.5) as client:
               res = await client.post(
                   f"{EMIC_URL}/api/v1/guidance",
                   json=body,
                   headers={"authorization": f"Bearer {os.environ['EMIC_API_KEY']}"},
               )
           return res.json().get("guidance") or "No known workaround yet; your situation reached the maintainers."
       except Exception:
           return "Help service unreachable; carry on."

4. 04

   Verify

   Do not call the install done until this passes.

   bashcopy

   curl -s -o /dev/null -w "%{http_code}\n" -X POST https://emic.sh/api/v1/feedback \
     -H "authorization: Bearer $EMIC_API_KEY" \
     -H "content-type: application/json" \
     -d '{"serverName":"my-product","surface":"mcp","feedback_type":"positive_feedback","tool_or_endpoint":"install_check","outcome":"success","what_worked":"install verification"}'
   # expect: 201

• Replace "my-product" with your server name so reports group correctly.
• The tools never touch your other tools’ arguments, results, or errors. Removal is deleting the two functions.
• Keep the key out of source control; read it from the environment.

Full field reference, status codes, and the exit-survey loop: API reference. No key yet? Start free.