@neurcode-ai/mcp-server

MCP server for the Neurcode deterministic governance runtime. Local-first. Zero-install via npx. Source-free runtime events. No telemetry.

Validate your environment

npx -y @neurcode-ai/mcp-server --doctor

That single command resolves the underlying Neurcode CLI through a four-step fallback (env var → workspace → PATH → npx -y @neurcode-ai/cli), probes it, and prints a structured ready/not-ready report. Works on enterprise laptops where npm install -g is blocked.

Get the MCP config snippet for your agent

npx -y @neurcode-ai/mcp-server --print-config claude     # or cursor / codex / gemini / copilot / all

Or let @neurcode-ai/skills do the install for you in a single command:

npx -y @neurcode-ai/skills quickstart

Adoption time: ~2 minutes on a warm npx cache.

Why this exists

Neurcode's governance runtime is deterministic, local-first, and inspectable. The CLI remains the local runtime brain. The MCP server gives AI coding agents a portable stdio doorway into that engine without requiring a global install. It also exposes a versioned source-free lifecycle ingress for agent hosts that can cooperate before an edit lands.

For MCP-native agentic coding, the primary loop is:

neurcode run codex --goal "<task>"
  -> neurcode_agent_session_handshake
  -> neurcode_agent_plan_capture
  -> neurcode_agent_edit_before before each proposed write
  -> exact approval / re-plan when Neurcode denies
  -> neurcode_agent_session_finish

This path is deliberately labelled cooperative: an MCP host must call the tools before edits for Neurcode to govern the flow. Claude Code hooks remain the current automatic pre-write hard_deny adapter.

The MCP server fixes this by being:

• npx-runnable — npx -y @neurcode-ai/mcp-server works through any corporate proxy that already reaches the public npm registry. No global install. No daemon. No admin approval.
• CLI-agnostic — the server resolves the underlying CLI through a deterministic four-step fallback. If neurcode is not on PATH, it falls back to npx -y --package=@neurcode-ai/cli and caches the resolution for the rest of the process lifetime.
• Boring — stdio transport, structured schemas via Zod, deterministic outputs, no telemetry, no hidden cloud calls.

Sample doctor output

Neurcode MCP — doctor
────────────────────────────────────────────────────────────
[ok]   node                        v20.11.0 (>=18 required)
[ok]   npx                         v10.8.2
[ok]   cli resolver                source=npx | npx -y --package @neurcode-ai/cli@latest neurcode
[ok]   cli probe                   --version succeeded in 1841ms (0.14.0)
[ok]   offline policy              standard (npx will fetch CLI on first invocation; subsequent calls are cached)
────────────────────────────────────────────────────────────
overall: ready

When the probe fails, the doctor surfaces up to 5 lines of CLI stderr plus a structured hint for common failure fingerprints (registry 404, DNS failure, timeout, permission error). The report is deterministic in structure across runs — only durationMs varies.

MCP tools exposed

All tools are deterministic at the governance layer — they shell out to the Neurcode CLI with --json and validate the response against published Zod schemas from @neurcode-ai/contracts.

| Tool | What it does | | --- | --- | | neurcode_agent_session_status | Inspect the active governed session and next required agent action. | | neurcode_agent_session_handshake | Handshake an MCP-capable agent into a launcher-created governed session. | | neurcode_agent_plan_capture | Capture the agent's source-free implementation plan before edits. | | neurcode_agent_plan_amend | Re-plan when scope changes during implementation. | | neurcode_agent_edit_before | Check a proposed file write before the MCP agent edits it. | | neurcode_agent_session_finish | Finish the governed session and write replayable evidence. | | neurcode_runtime_adapter_capabilities | List available runtime adapters and whether they hard-deny, cooperate, observe, or run as a post-change backstop. | | neurcode_runtime_event | Submit a normalized source-free agent lifecycle event such as session.start, plan.capture, or edit.before. | | neurcode_session_approve | Apply an exact-path approval to the current governed session. | | neurcode_session_amend_plan | Amend the current source-free agent plan as implementation understanding evolves. | | neurcode_session_obligations | Inspect live source-free architecture obligations. | | neurcode_session_waive_obligation | Record a human-authorized obligation waiver with bounded expiry. | | neurcode_plan | Generate an execution plan from a natural-language intent. | | neurcode_prompt | Render a Cursor/Claude prompt from an existing plan. | | neurcode_verify | Run deterministic governance verification against a plan, with optional policy-only mode. | | neurcode_governance_loop | verify → remediate-on-fail → re-verify in a single MCP call. | | neurcode_runtime_guard | Pre-generation deterministic enforcement (start/check/status/stop). | | neurcode_remediate | Run the controlled remediation ship loop and re-verify. | | neurcode_contract_import | Import an external plan (Claude/Cursor/Codex) into a Neurcode contract. | | neurcode_feedback_submit | Submit false-positive / false-negative feedback. | | neurcode_feedback_list | List submitted feedback for a verification ID. | | neurcode_feedback_stats | Aggregate feedback quality stats. | | neurcode_feedback_review | Admin review (approve/reject) for submitted feedback. | | neurcode_ship | End-to-end ship workflow (plan → apply → verify → publish). | | neurcode_simulate | Predict blast radius and regressions before merge. | | neurcode_ship_runs | List persisted ship runs for the current repository. | | neurcode_ship_resume | Resume a persisted ship run by ID. | | neurcode_ship_attestation_verify | Verify a release attestation JSON document. |

CLI resolution

The server resolves the underlying neurcode CLI binary lazily, on first tool call, and caches the result for the rest of the process. Resolution order:

1. NEURCODE_CLI_BIN — explicit absolute path to a binary or .js entry (executed via node).
2. Workspace CLI at ../../cli/dist/index.js (monorepo development mode).
3. neurcode on PATH (verified via which/where plus an executable check).
4. Zero-install fallback: npx -y --package=@neurcode-ai/cli@<version> neurcode. Set NEURCODE_CLI_VERSION to pin a specific version (default: latest).

Step 4 is the load-bearing one for enterprise adoption. On a fresh laptop that has never seen Neurcode, the first MCP tool call performs a one-time npm registry fetch (typically 2–10 seconds), populates the per-user npx cache at ~/.npm/_npx/, and all subsequent calls reuse that cached binary with ~100ms of npx overhead.

Configuration

| Env var | Purpose | | --- | --- | | NEURCODE_CLI_BIN | Absolute path to the neurcode binary or .js entry. Bypasses all other resolution steps. | | NEURCODE_CLI_VERSION | Version tag used by the npx fallback. Default latest. | | NEURCODE_OFFLINE=1 | Documentary only — the doctor surfaces this as "offline-friendly env detected." | | npm_config_offline=true | Standard npm offline flag; recognised by the doctor. |

Operational properties

• No telemetry. The server makes no outbound HTTP calls of its own. It only spawns the CLI as a subprocess.
• No persistent state. Every tool call is a fresh CLI invocation.
• One local engine. The normalized runtime ingress delegates to the same session engine used by the automatic Claude Code hooks.
• Deterministic. Identical inputs produce identical outputs because the CLI itself is deterministic at the governance layer (replay checksums, canonical finding order, structural verification).
• Inspectable. Every tool response includes the exact command line that was executed, so the user can re-run it manually for debugging.

Security posture

• The server only spawns the resolved neurcode binary plus, if needed, npx. No bash, no sh, no shell interpolation.
• CLI arguments are constructed from typed Zod-validated inputs, never from string concatenation.
• Working directory for each tool call is opt-in via the cwd parameter and defaults to process.cwd() of the MCP server process.
• The CLI itself enforces Neurcode's governance scope guard — the MCP surface inherits that boundary unchanged.

See docs/mcp/security-posture.md and docs/mcp/trust-boundaries.md for the full posture.

Local development

pnpm --filter @neurcode-ai/mcp-server build
pnpm --filter @neurcode-ai/mcp-server test
pnpm --filter @neurcode-ai/mcp-server run pack:dry-run
node packages/mcp-server/dist/index.js --doctor

pack:dry-run builds the package, runs npm pack --dry-run --json, and fails if the publishable tarball would omit dist/index.js, type definitions, README, the executable shebang, or the public package metadata. Run it before any npm publish so the documented npx -y @neurcode-ai/mcp-server entry point is never ahead of the package.

License

MIT