@mushi-mushi/mcp

Your AI wrote it. Mushi tells you why it broke.

Model Context Protocol server that wires Mushi into Cursor, Claude Code, and any MCP client. Pull fix context, review bugs, and dispatch fixes without a second LLM vendor key.

Wire it into Cursor, Claude Code, or any MCP client in one command:

npx mushi-mushi setup --ide cursor
# or: npx mushi-mushi setup --ide claude

That command reads CLI config at ~/.config/mushi/config.json (legacy ~/.mushirc auto-migrates), writes .cursor/mcp.json with the mushi-<slug> server block, and prints "Done; restart Cursor and ask: list mushi tools". No copy-pasting environment variables.

What this is, and what it isn't

• This package (@mushi-mushi/mcp) is the MCP server; runs locally next to your editor, talks to the Mushi API, and presents bug reports as MCP tools/resources to your coding agent. Always install it by its scoped name (npx -y @mushi-mushi/mcp@latest); the bare mushi-mcp name was never published to npm.
• @mushi-mushi/agents ships the MCP client adapter; used by the autofix orchestrator when your project's autofix_agent = 'mcp'. See packages/agents/src/adapters/mcp.ts.
• The generic_mcp adapter shipped before V5.3 was a misnomer (it spoke plain REST). It is now RestFixWorkerAgent; the old export is kept as a deprecated alias for one more minor.

Quick start

0. One-click: "Add to Cursor" deeplink

The Mushi admin console (Admin → MCP → Setup tab) generates a one-click deeplink that opens Cursor's "Install MCP server?" dialog with your project ID and a freshly-minted mcp:write key already embedded:

cursor://anysphere.cursor-deeplink/mcp/install?name=mushi-<project>&config=<base64>

Click "⚡ Add to Cursor" (or "Add to VS Code"); Cursor prompts you to confirm, then writes the server block into your global mcp.json automatically. No copy-pasting.

Security note: The deeplink mints a dedicated mcp:write key (or mcp:read for read-only), separate from your app's SDK key. Your SDK key (the report:write-scoped key your app sends bug reports with) should never carry mcp:write; it would expose admin-level triage and fix dispatch to anyone who extracted it from your browser bundle. The deeplink mint enforces this separation automatically. See API key scopes below.

1. One-liner CLI (recommended for first-time setup)

# First: make sure you've logged in
npx mushi-mushi login --api-key mushi_xxx --endpoint https://<ref>.supabase.co/functions/v1/api

# Then wire your IDE
npx mushi-mushi setup --ide cursor          # Cursor
npx mushi-mushi setup --ide claude          # Claude Code / Claude Desktop
npx mushi-mushi setup --ide cursor --with-rules  # also write .cursorrules

2. With Claude Desktop (manual)

Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "mushi-mushi": {
      "command": "npx",
      "args": ["-y", "@mushi-mushi/mcp@latest"],
      "env": {
        "MUSHI_API_KEY": "mushi_xxxxxxxxxxxxxxxxxxxx",
        "MUSHI_PROJECT_ID": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
        "MUSHI_API_ENDPOINT": "https://<your-ref>.supabase.co/functions/v1/api"
      }
    }
  }
}

Restart Claude Desktop. You should see a hammer icon in the chat input; click it to see the Mushi Mushi tools.

Where do I find these values?

• MUSHI_API_KEY: Admin → Connect or MCP setup; mint an mcp:read / mcp:write key. This is not the SDK ingest key from Setup → Verify (report:write) and not a BYOK key from Settings → API Keys.
• MUSHI_PROJECT_ID: Admin console → click your project → copy the UUID below the project name (e.g. 542b34e0-019e-41fe-b900-7b637717bb86)
• MUSHI_API_ENDPOINT: Shown when you mint the MCP key, or use your project's API base (https://<ref>.supabase.co/functions/v1/api)

Or visit Admin → MCP in the console for a one-click pre-filled config snippet.

3. With Cursor (manual)

In Cursor settings, open MCP → Add new MCP server and paste:

npx -y @mushi-mushi/mcp@latest

Then set the same three environment variables:

Without MUSHI_PROJECT_ID the server starts but scoped tools return an empty result with a message pointing you here.

4. From the command line

MUSHI_API_KEY=mushi_xxxxxxxxxxxxxxxxxxxx \
MUSHI_PROJECT_ID=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx \
npx -y @mushi-mushi/mcp@latest

The server speaks stdio MCP transport by default; your client launches it as a subprocess.

5. Hosted Streamable HTTP (no subprocess)

The Mushi backend now exposes the same tool catalog over the Streamable HTTP transport (dual-era: MCP 2024-11-05 … 2025-11-25 legacy and the current 2026-07-28 revision) at /functions/v1/mcp. Use this when you want to skip the local subprocess; typical for OpenAI Agents SDK, ChatGPT Agent, hosted CrewAI, or any orchestrator that talks remote MCP:

// .cursor/mcp.json — example (hosted HTTP)
{
  "mcpServers": {
    "mushi-mushi-hosted": {
      "type": "http",
      "url": "https://<your-ref>.supabase.co/functions/v1/mcp",
      "headers": {
        "Authorization": "Bearer mushi_xxxxxxxxxxxxxxxxxxxx",
        "X-Mushi-Api-Key": "mushi_xxxxxxxxxxxxxxxxxxxx",
        "X-Mushi-Project-Id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
      }
    }
  }
}

Cursor icon: HTTP MCP URLs on *.supabase.co often show the Supabase favicon in Cursor settings; not a Mushi bug. Use stdio (command + npx @mushi-mushi/mcp) for the red 虫 stamp, or set "icon": "https://kensaur.us/mushi-mushi/docs/integrations/mushi-mark-512.png" in your server block. The hosted endpoint also emits MCP serverInfo.icons and serves inline SVG at ?icon=1.

Feature groups (?features= / MUSHI_FEATURES)

Full catalog is 117 tools (stdio / MUSHI_FEATURES=all). The hosted HTTP endpoint exposes a leaner subset filtered by feature groups (see mcp-hosted-tool-manifest.json). New installs now default to the lean triage,fixes,inventory,setup,docs set automatically (stdio: when MUSHI_FEATURES is unset; HTTP: pass the same ?features= on the URL). To change the surface:

• Stdio: MUSHI_FEATURES=all for the full catalog, or a CSV like MUSHI_FEATURES=triage,qa,skills
• HTTP: ?features=all or ?features=triage,qa,skills on the MCP URL

Renamed tools (inventory_get → get_inventory, inventory_diff → diff_inventory, inventory_findings → list_gate_findings, fix_suggest → suggest_fix, graph_neighborhood → get_graph_neighborhood, graph_node_status → get_graph_node) and the consolidated setup tooling (setup_check / ingest_setup_check / diagnose_connection → diagnose_setup; get_activation_status → activation_status; get_reporter_thread → get_report_timeline) are documented in the changelog; update calls to the new names.

New unified tools: diagnose_setup (replaces the setup trilogy), search_mushi_docs (keyword doc search).

Append ?read_only=1 to the URL to hide write tools (Supabase-parity mode).

Programmatic imports

For custom MCP hosts or tests:

Cursor config hygiene

1. One global MCP config; keep mushi in ~/.cursor/mcp.json only. Do not duplicate mushi / mushi-stdio in per-project .cursor/mcp.json (prevents connection storms). Project repos may ship {} or a comment pointing to the global file.
2. Windows paths; use forward slashes in JSON (C:/Users/...) or escaped backslashes (C:\\Users\\...). Raw \f, \n, \t in paths corrupt JSON.
3. Multi-project; either one HTTP server per project (distinct server name + X-Mushi-Project-Id) or one stdio server and pass projectId on each tool call.

Tool parameters are camelCase (projectId, reportId, includeRaw). The snake_case spelling of any of them (project_id) is accepted too, on both transports, so older prompts and configs keep working. 4. After editing global config; fully restart Cursor (MCP panel must reload).

X-Mushi-Project is deprecated for project UUID (collision with legacy slug header).

The endpoint accepts JSON-RPC 2.0 over POST (returns application/json or text/event-stream per content negotiation), opens an SSE stream on GET for server-pushed notifications, and accepts DELETE for session termination. Auth is the same dual-mode API-key / JWT used everywhere else on /v1/admin/*.

Tools

Read

Write / agentic

Codebase (indexed repos)

When codebase indexing is enabled on a project, these tools ground on project_codebase_files (+ wiki chunks when configured):

Need a tool that isn't here? Open an issue at github.com/kensaurus/mushi-mushi/issues and tag it mcp.

Tool annotations (what clients see before invoking)

Every tool is registered via server.registerTool() with MCP 2025-10 tool annotations so clients (Cursor, Claude Desktop, Continue, Cline, Zed) can render a proper "is this safe to auto-invoke?" UI without calling the tool first. The annotations come from a single source of truth; src/catalog.ts; mirrored into the admin console (apps/admin/src/lib/mcpCatalog.ts) and guarded against drift by scripts/check-mcp-catalog-sync.mjs.

The same catalog entries power the /mcp beginner console in the admin app; so the tool catalog the agent sees and the tool catalog the human operator reads can never disagree.

Progress notifications on long-running tools

dispatch_fix emits an MCP notifications/progress event the moment the orchestrator accepts the request, so clients that support progress (Cursor, Claude Desktop) can render a live "Dispatching fix…" indicator instead of freezing until the HTTP round-trip returns. The notification mirrors the ProgressToken the client passed in _meta.progressToken; clients that don't pass one get the normal non-streaming response, unchanged.

Resources

Full list (8). See also the generated catalog at kensaur.us/mushi-mushi/docs/sdks/mcp-tools.

Prompts

Named templates the MCP client surfaces in its slash-menu. Each one bakes in the house voice ("lead with the fix, skip the preamble") so agents produce consistent outputs across editors.

Environment variables

If a client passes a variable reference through unexpanded (the server receives the literal text ${MUSHI_API_KEY}), the server treats it as unset: it falls back to the mushi login config, or serves setup mode and prints which client syntax to use. Claude Desktop expands no variables; Cursor and VS Code expand ${env:MUSHI_API_KEY}; Claude Code expands ${MUSHI_API_KEY}.

Storing the key in .env.local

The MCP binary reads these three vars from process.env on spawn; that means anywhere you normally put env vars works. The zero-friction path:

1. In the admin console, mint a key and pick Copy as .env.local on the reveal card. You get a pre-formatted block:

   bash

   # Mushi MCP; drop into .env.local (gitignored). The MCP binary picks these up on spawn.
   MUSHI_API_ENDPOINT=https://dxptnwrhwsqckaftyymj.supabase.co/functions/v1/api
   MUSHI_PROJECT_ID=<your-uuid>
   MUSHI_API_KEY=mushi_…
   

2. Paste it into your repo's .env.local (already gitignored by every Vite / Next.js / Node project scaffold). Confirm .env.local is in .gitignore if you're in an unusual setup.

3. Tell your MCP client to inherit the shell env. For Cursor, the simplest form:

   json

   {
     "mcpServers": {
       "mushi-mushi": {
         "command": "npx",
         "args": ["-y", "@mushi-mushi/mcp@latest"]
       }
     }
   }
   

   Cursor spawns the subprocess with the parent shell's env, so as long as you ran Cursor from a terminal that has .env.local sourced (or you're using direnv / dotenv-cli), the three vars are already in place. If you prefer to inline them; Cursor / Claude Desktop both support an env block in mcp.json; use the Copy as .cursor/mcp.json tab on the reveal card, which hard-codes the three values into the JSON for you.

4. Never commit .env.local, and never paste a key into a repo-tracked .cursor/mcp.json. If you accidentally do, rotate the key from the admin console; the denormalised owner binding is rebuilt automatically on rotation.

API key scopes

The admin routes the MCP server hits enforce per-key scopes. When you mint a key, pick the smallest scope that works for your agent workflow:

The middleware replies 403 INSUFFICIENT_SCOPE with a human-readable message if your key is missing a required scope; no silent failures.

When MCP helps (and when it doesn't)

Useful if you already fix bugs in an AI-augmented editor. If your team still opens bugs exclusively in Jira and writes patches longhand, this server is solving a problem you don't have yet; use the SDK + Discord webhook and come back later.

For teams that live in Cursor / Claude Code / Continue / Cline / Zed / Windsurf:

MCP spec coverage

Detail and tool tables: docs /sdks/mcp and the generated MCP tools reference page. Open an issue for a waiting-on-clients row once ≥2 major clients ship support.

Admin console: /mcp page

The admin app ships an /mcp page (sidebar → Act → MCP) with connection status, install snippets, the use-case table above (clickable into the catalog), and the full tool / resource / prompt list from the same catalog.ts the server registers.

The page is the recommended first stop for a new team member; it takes about 60 seconds to go from "I have a Mushi account" to "Cursor is calling get_recent_reports for me". The source of truth lives at apps/admin/src/pages/McpPage.tsx.

Security

• The server runs locally; your API key never leaves your machine except in calls to your configured MUSHI_API_ENDPOINT.
• Scope keys tightly. Give MCP the smallest scope that works; mcp:read is fine for 90% of agent loops.
• Keep your SDK key (report:write) separate from your MCP key. Your app's Mushi SDK key is embedded in client-side code (e.g. NEXT_PUBLIC_MUSHI_API_KEY) and should carry only report:write scope. This scope is intentionally rejected by every admin route; so even if extracted from a browser bundle, it cannot triage, dispatch fixes, or mutate report status. Mint a dedicated mcp:write key for Cursor/Claude (use the "⚡ Add to Cursor" deeplink on the /mcp console page; it mints one automatically). If you discover your public SDK key carries mcp:write, rotate it immediately.
• Never paste a service-role key; it bypasses RLS on every table.
• Rotate keys from the admin console if a laptop is lost; the denormalised owner binding is rebuilt automatically on rotation.
• The server logs to stderr; redirect to a file if you need an audit trail.

Testing locally

Three layers of testing, each solving a different problem.

Layer 1; In-process integration tests (fastest, no subprocess)

Real Client ↔ Server handshake over InMemoryTransport with a mocked fetch. Catches protocol regressions in under a second.

pnpm --filter @mushi-mushi/mcp test
# 49/49 pass; handshake, tool contracts, envelope unwrapping, scope errors, annotation contract, outputSchema, catalog parity

Layer 2; Stdio smoke test (verifies the built bin boots)

Spawns dist/index.js with a dummy unreachable endpoint and confirms it advertises the expected tools/resources/prompts over stdio. Good CI gate before publishing.

pnpm --filter @mushi-mushi/mcp build
pnpm --filter @mushi-mushi/mcp test:smoke
# OK; prints live tool/resource/prompt counts from the catalog
# (see packages/mcp/src/catalog.ts — currently 117 tools / 8 resources / 4 prompts)

Layer 3; Full localhost E2E (real binary + real backend behaviour)

Boots a tiny node:http mock of /v1/admin/*, spawns the real MCP binary pointed at it, and runs a real StdioClientTransport client through every tool + resource + a scope-denial path. This is the closest you can get to a production handshake without running Supabase Edge Functions.

pnpm --filter @mushi-mushi/mcp build
node packages/mcp/scripts/localhost-e2e.mjs
# 27/27 assertions; every tool, every resource, scope denial surfaced correctly

The harness is also the quickest way to iterate on new tools: extend the FIXTURES + the route switch in scripts/localhost-e2e.mjs, rebuild, rerun. No migrations, no Supabase boot time, no DB state.

Configuring against your own localhost

When you're ready to wire the MCP into your local Mushi Mushi stack (i.e. pnpm dev is running the admin console + local Supabase), use these endpoints:

Minting a localhost key

1. Start the stack: pnpm dev (admin on :6464, Supabase on :54321).
2. Sign in and open Settings → API keys.
3. Click New key, pick MCP read or MCP read-write (the scope picker on the "New key" form), and copy the plain-text key that appears once; it's not retrievable later.
4. The admin console URL is http://localhost:6464/projects/<uuid>/...; the <uuid> is your MUSHI_PROJECT_ID.

Pointing Cursor/Claude Desktop at localhost

Replace the public endpoint block in your client's MCP config with the three env vars above. For Cursor, this lives in .cursor/mcp.json at your repo root:

{
  "mcpServers": {
    "mushi-mushi-local": {
      "command": "node",
      "args": ["/absolute/path/to/mushi-mushi/packages/mcp/dist/index.js"],
      "env": {
        "MUSHI_API_ENDPOINT": "http://localhost:54321/functions/v1/api",
        "MUSHI_API_KEY": "mushi_abc…",
        "MUSHI_PROJECT_ID": "00000000-0000-0000-0000-000000000000"
      }
    }
  }
}

Rebuild the package (pnpm --filter @mushi-mushi/mcp build) after any MCP source change; Cursor re-spawns the subprocess on config reload but doesn't recompile for you.

Sanity check: did it connect?

In Cursor chat, type /; you should see the Mushi Mushi slash-prompts (/summarize_report_for_fix, /explain_judge_result, /triage_next_steps). Or ask the agent directly: "Use the Mushi MCP to list my recent reports". If scope is wrong you'll see the [INSUFFICIENT_SCOPE] error text verbatim; rotate the key with the right scope and retry.

Debug MCP logs in Cursor

If tools are not showing up or returning unexpected errors:

1. Check the Cursor MCP logs: Cursor → Help → Toggle Developer Tools → Console. Filter by mushi.
2. Verify the server started: In the MCP panel (Cursor → Settings → MCP), look for a green dot next to the Mushi server.
3. Check scope errors: A INSUFFICIENT_SCOPE response means your API key lacks the required scope; mint a new key with mcp:read (or mcp:write for mutating tools).
4. Run the health check: /test-mushi-mcp command or call list_projects; a clean response confirms auth is working.
5. Restart Cursor: After changing environment variables or mcp.json, restart Cursor to pick up the new config.

Mushi vs Sentry MCP

Both are complementary; use Sentry for exception noise, Mushi for "the user says it's broken" signal.

See also

• Fix orchestrator; the agentic fix architecture this server feeds into.
• MCP tool reference; every tool's parameters, generated from the catalog.
• @mushi-mushi/agents; orchestrator that consumes MCP-exposed fix workers.

License

MIT

_{Monorepo scale (July 2026): 64 edge functions · 413 SQL migrations · 13 outbound plugins · 11 inbound adapters · 19 pipeline agents. Canonical counts: docs/stats.md · pnpm docs-stats}