MCP Setup#

The Mandu MCP server is the agent-native interface to the framework. It exposes every meaningful operation — negotiate a feature, generate artifacts, run guards, begin a transaction, drive ATE — as a typed tool the agent calls instead of shelling out.

This page covers how to wire it into the three clients Mandu officially supports: Claude Code, Cursor, and Gemini CLI.

What the server exposes#

The server is published as @mandujs/mcp and ships three executable names via its bin block: mandu-mcp, mandujs-mcp, and mcp. The Mandu CLI always uses mandu-mcp to avoid colliding with the Python mcp CLI.

Tools are organised into categories and surface with dot-notation names. The built-in categories are:

A quick tour from the terminal is the fastest way to see the live list:

bunx mandu mcp --list
bunx mandu mcp mandu.negotiate --intent "add payment integration" --featureName payment

The mandu mcp CLI bridge reuses the same registry the server loads, so any tool you see there is exactly what the agent sees.

Tool profiles#

The server reads the MANDU_MCP_PROFILE environment variable at startup and filters the categories it registers:

• minimal — spec, project, guard, generate. Roughly 15 tools. Good for first-run or constrained context windows.
• standard — minimal plus contract, slot, hydration, seo, component, kitchen, composite. Roughly 40 tools.
• full (default) — every category registers, including ate, transaction, brain, decisions.

Set the variable in your client config if you want a leaner surface:

{
  "env": { "MANDU_MCP_PROFILE": "standard" }
}

Claude Code#

mandu init writes two files so Claude Code picks up the server without any manual work:

• .mcp.json — Claude Code project-scope MCP registration.
• .claude.json — Claude local scope, so claude mcp list shows it.

Both files contain the same server entry:

{
  "mcpServers": {
    "mandu": {
      "command": "bunx",
      "args": ["mandu-mcp"],
      "cwd": "."
    }
  }
}

Restart Claude Code, open the project, and run the MCP inspector from the command palette. You should see the mandu server with its tool count. If you already maintain .mcp.json, mandu init preserves existing keys and only adds or updates the mandu entry; it also backs up malformed files to .mcp.json.bak.

Cursor#

Cursor reads MCP servers from ~/.cursor/mcp.json (user scope) or .cursor/mcp.json (project scope). Use the same server block:

{
  "mcpServers": {
    "mandu": {
      "command": "bunx",
      "args": ["mandu-mcp"],
      "cwd": "${workspaceFolder}"
    }
  }
}

Reload Cursor. The Mandu tools appear under the MCP section of the agent panel.

Gemini CLI#

Gemini CLI reads .gemini/settings.json at the project root. mandu init creates the directory and writes the server entry automatically:

{
  "mcpServers": {
    "mandu": {
      "command": "bunx",
      "args": ["mandu-mcp"],
      "cwd": "."
    }
  }
}

List available tools to confirm:

gemini mcp list
gemini mcp call mandu mandu.guard.check

Verifying the connection#

Regardless of client, the quickest smoke test is three calls:

bunx mandu mcp --list                 # registry loaded?
bunx mandu mcp mandu.guard.check      # guards runnable?
bunx mandu mcp mandu.tx.status --json # server reachable end-to-end?

If any of those fail, run bunx mandu doctor — it validates bun, the Mandu version, and the MCP registration files.

Hot reload of configuration#

The server watches mandu.config.ts. When it changes, the active MCP session reloads settings without restarting, and the client receives a logging notification. You do not need to restart the client for most config edits.

Tool registration itself is fixed at startup, so adding a new category means relaunching the server (close and reopen the client session).

Do not do this

• Do not invoke the server through a generic mcp command; on systems with the Python mcp CLI installed it will shadow ours. Always use bunx mandu-mcp or the command / args pair shown above.
• Do not hand-edit .mcp.json to remove backup files. If the JSON is malformed Mandu rewrites it and preserves the original as .mcp.json.bak.
• Do not assume every tool is present: the default profile is full, but CI or constrained setups may run minimal and hide whole categories.

🤖 Agent Prompt#

Apply the guidance from the Mandu docs page at https://mandujs.com/docs/build-with-agents/mcp-setup to my project.

Summary of the page:
The Mandu MCP server ships as the bin mandu-mcp from @mandujs/mcp. Client JSON config points at command bunx, args [mandu-mcp]. Tools are namespaced mandu.<category>.<verb> and filtered by the MANDU_MCP_PROFILE env (minimal|standard|full).

Required invariants — must hold after your changes:
- The MCP server is launched as bunx mandu-mcp, never via a Python shim named mcp
- Tool names use dot-notation under the mandu prefix (for example mandu.negotiate, mandu.generate, mandu.guard.check)
- MANDU_MCP_PROFILE gates which tool categories are registered at startup
- mandu init writes .mcp.json, .claude.json, and .gemini/settings.json atomically with backups

Then:
1. Make the change in my codebase consistent with the page.
2. Run `bun run guard` and `bun run check` to verify nothing
   in src/ or app/ breaks Mandu's invariants.
3. Show me the diff and any guard violations.