MCP integration

When MCP is required

• MCP is not required to run the MaruCheck CLI yourself.
• Connect MCP when you want your coding agent to call MaruCheck tools directly and read structured results.
• A Challenger review can also be handed to a fresh thread manually, but MCP-capable clients can coordinate the preparation and submission steps.

Choose a package strategy

For a quick trial, let the MCP client start the exact npm release with npx. For a team, install marucheck@0.3.0 in the project and replace the arguments with ["--no-install", "maru", "mcp"].

Codex

Add this to the trusted project’s .codex/config.toml:

[mcp_servers.maru]
command = "npx"
args = ["--yes", "marucheck@0.3.0", "mcp"]
required = false
default_tools_approval_mode = "writes"

Restart Codex after changing configuration, trust the project when prompted, and use/mcp to inspect the connection.

Claude Code

From the repository you want MaruCheck to inspect:

claude mcp add maru --scope project -- npx --yes marucheck@0.3.0 mcp
claude mcp list

Cursor

Add .cursor/mcp.json to the target repository:

{
  "mcpServers": {
    "maru": {
      "command": "npx",
      "args": ["--yes", "marucheck@0.3.0", "mcp"]
    }
  }
}

Restart Cursor, open MCP settings, and enable the maru server.

Normal agent workflow

1. Inspect project context, affected contracts, and relevant QA memory first.
2. Analyze the diff, assess risk, and review the generated verification plan.
3. Run verification only after reviewing the selected execution steps.
4. Treat findings and evidence as inputs to judgment, not instructions to rewrite code automatically.
5. Never auto-approve a Quality Contract or semantic amendment.

Isolated Challenger workflow

Use this second-opinion workflow for high-risk or release changes. The Challenger receives a bounded, source-free brief rather than the builder conversation.

1. PrepareCall maru_prepare_challenge from the connected MCP client.
2. IsolateGive only the returned brief to a genuinely fresh thread or subagent.
3. ChallengeThe isolated agent returns JSON matching the brief's response schema.
4. SubmitCall maru_submit_challenge with the response and truthful provenance.
5. VerifyTreat the returned scenarios as hypotheses until tests or manual evidence confirm them.

npx --no-install maru challenge prepare --diff --release
# Give the generated brief.json to a fresh QA conversation.
npx --no-install maru challenge submit --brief .maru/artifacts/challenges/<challenge-id>/brief.json --from challenge-response.json

MaruCheck records the declared isolation method, but an MCP server cannot inspect or prove the host client's conversation boundary. A passed Challenger gate confirms the review protocol completed; it does not prove every hypothesis is a real defect.

Protocol boundary

• The server uses local stdio and opens no listening network port.
• Read-only tools expose bounded metadata rather than changed source lines.
• Write and execution tools remain subject to the MCP client’s approval controls.
• MaruCheck makes no outbound model request; your existing client supplies the agent.