Codex Harness Mcp

Codex Harness MCP

A local harness-engineering control plane for Codex CLI and MCP-compatible coding agents.

View on skills.sh

codex-harness-mcp turns loose agent work into an auditable loop: define a bounded contract, query local project knowledge, record research and implementation lessons, capture raw traces, store verification evidence, enforce a local governance policy, export PASS/FLAG/BLOCK governance reports, export a trace-level observability report, compare harness profiles with eval runs, record harness-change proposals and promotion decisions, export the harness as natural-language control logic, and run a gate before claiming completion. It ships a multi-client installer for Codex CLI, Claude Code, OpenCode, Kilo, Gemini CLI, Cursor, VS Code/Copilot, Cline, Windsurf, and best-effort Roo Code project config.

At a glance

| Area | What it gives MCP clients | | --- | --- | | Contracts | A small, explicit goal with budgets, permissions, expected outputs, and completion conditions. | | Persistent memory | Local RAG over research notes, implementation lessons, and project knowledge. | | Recovery | Raw traces and next-step recommendations after failures or uncertain work. | | Verification | Structured records for commands/manual checks run outside the MCP server. | | Governance | A local policy plus PASS/FLAG/BLOCK audit for contract quality, outputs, raw traces, verification, gates, side effects, and subagent bounds. | | Observability | A local "flight recorder" report for contract state, traces, eval posture, memory, governance, safety, and blind spots. | | Multi-client setup | Safe config generation for major MCP coding clients without running their CLIs. | | Harness evals | Profiles, eval cases, eval runs, metrics, comparisons, and regressions. | | Meta-Harness-lite | Proposal and promotion records for harness changes, with optimization, holdout, regression, risk, and follow-up evidence. | | Natural-language harness | A portable markdown spec of roles, stages, tools, state semantics, failure taxonomy, and stop rules. | | Safety posture | Dependency-free local Node server, no shell execution, no remote calls, no credential handling. |

Why agents need a harness

Long-running agent work often fails in quiet ways:

• context gets compacted
• research is repeated
• failures are summarized too early
• verification evidence disappears
• harness changes are promoted without holdout evidence
• "done" gets claimed before the work is actually checked

This project gives coding agents a durable system of record for that work. It does not replace the agent or run tasks for it. It gives MCP-capable clients a local harness: state, contracts, memory, traces, eval records, promotion evidence, and completion gates.

Modern harness-engineering research points in the same direction: the orchestration around an LLM can change task performance dramatically. This MCP focuses on the practical, low-risk layer of that idea: make the loop explicit, make evidence durable, and make harness changes measurable before promoting them.

This MCP gives Codex and compatible coding CLIs a small local control plane:

• execution contracts before implementation
• project-local RAG from research and implementation lessons
• raw traces for attempts, failures, decisions, and verification
• structured verification records
• project-local governance policy and audit report
• trace-level observability report for AgentOps-style review
• harness profiles and eval run comparisons
• Meta-Harness-lite proposal and promotion-decision records
• natural-language harness spec export
• next-step recovery after a failure
• compact handoff context for long sessions
• explicit completion gates

The goal is not to replace Codex, Claude Code, OpenCode, Kilo, Gemini CLI, Cursor, or other clients. The goal is to give them the same durable working memory and safer operating loop through MCP.

What makes it different

• Local first: all project state lives under .codex-harness/.
• Client portable: installer can write the known MCP config shapes for the major coding clients.
• Scanner friendly: the MCP server uses only Node.js built-in modules.
• No command execution: verification is recorded, not executed by the MCP.
• Governed: harness_write_governance_policy, harness_audit_governance, and harness_export_governance_report make contract quality and completion evidence explicit.
• Prompt-injection bounded: stored user/source text is returned inside `` blocks.
• Harness-aware: evals, profiles, proposal records, and promotion decisions are first-class data.
• Observable: harness_export_observability_report and harness://observability/report expose trace, eval, memory, governance, and blind-spot signals.
• Portable: harness://harness/spec exports the current loop as a natural-language harness spec.

Install

Install the skill:

npx skills add chapzin/codex-harness-mcp -g -a codex -y --copy

Then run the bundled installer from the installed skill directory, or from this repository.

Codex only:

node scripts/install-codex-harness-mcp.mjs

All supported MCP clients:

node scripts/install-codex-harness-mcp.mjs --clients all --scope auto --project .

Specific clients:

node scripts/install-codex-harness-mcp.mjs --clients codex,claude-code,opencode,kilo,gemini,cursor,vscode,cline,windsurf,roo --scope auto --project .

Verify:

codex mcp list

Expected MCP entry:

codex-harness  node  ~/.codex/mcp-servers/codex-harness-mcp/src/server.mjs

One-minute workflow

1. Ask Codex to use the harness.
2. Bootstrap or migrate .codex-harness/.
3. Query existing local knowledge before repeating research.
4. Create a small contract.
5. Work inside the contract boundaries.
6. Record attempts, failures, decisions, research, lessons, and verification evidence.
7. Audit governance with harness_audit_governance; stop on BLOCK and call out FLAG.
8. Export the observability report when the run gets long, risky, or unclear.
9. If changing the harness itself, record profiles, evals, proposals, and promotion decisions.
10. Run the completion gate before saying the work is done.

Supported clients

The installer can generate configs for:

• Codex CLI
• Claude Code
• OpenCode
• Kilo CLI / Kilo Code
• Gemini CLI
• Cursor
• VS Code / GitHub Copilot MCP
• Cline
• Windsurf Cascade
• Roo Code

See [Multi-client MCP setup](docs/multi-client-setup.md) for exact files and config shapes.

Roo Code is included as a project-config best-effort target because the config shape is common in the ecosystem, but the official Roo Code docs currently announce product shutdown on May 15, 2026. Prefer Cline, VS Code/Copilot, Cursor, Claude Code, OpenCode, Kilo, or Gemini CLI for longer-lived setups.

Start with this prompt

Use codex-harness. Bootstrap the project, migrate old harness state if needed, query local knowledge, create a small contract, record traces and lessons, record verification evidence, export the observability report when the run gets complex, record eval/profile/proposal evidence if changing the harness, and run the eval gate before saying the task is done.

For harness optimization work:

Use codex-harness. Record the current harness profile, create optimization and holdout eval cases, store externally run eval results, compare baseline and candidate runs, record a harness proposal, then record a promotion decision only if holdout/regression evidence supports it.

For research-heavy implementation:

Use codex-harness. Query local knowledge first. If missing or stale, research externally, store useful sources with harness_record_research, implement inside a small contract, record lessons, and gate completion with verification evidence.

What it adds to MCP coding agents

| Capability | What it solves | | --- | --- | | Contracts | Keeps work bounded with goals, permissions, budgets, outputs, and completion conditions. | | Local knowledge RAG | Lets future sessions reuse project research and implementation lessons. | | Raw traces | Preserves the exact failure or verification signal for recovery. | | Verification records | Stores command output or manual checks without the MCP running shell commands. | | Governance audit | Produces a PASS/FLAG/BLOCK closeout posture from policy, contract, outputs, trace, verification, and gate evidence. | | Observability report | Turns harness state into a trace-level review of evidence, evals, memory, governance, safety, and blind spots. | | Eval cases and runs | Measures harness profile changes with score, verdict, cost, token, time, and regression metadata. | | Harness profiles | Lets Codex compare minimal, standard, verifier-heavy, research-heavy, and custom harness modes. | | Meta-Harness-lite records | Stores proposed harness changes, expected gains, baseline/candidate/holdout evidence, accepted risks, and promotion decisions. | | Natural-language harness spec | Exports roles, stages, adapters, state semantics, failure taxonomy, and stop rules as a portable markdown spec. | | Next-step recovery | Helps narrow the next attempt after failure instead of thrashing. | | Completion gates | Makes "done" an explicit evidence check, not a vibe. | | Handoff context | Produces compact restart context after compaction or session changes. |

Harness research alignment

The current implementation is aligned with modern harness-engineering practice around contracts, durable artifacts, trace-backed recovery, local knowledge, eval records, Meta-Harness-lite promotion evidence, natural-language harness export, and explicit gates.

It is intentionally a small local control plane, not a full benchmark runner or autonomous Meta-Harness optimizer. The MCP stores and exposes evidence. Codex, the user, or external benchmark tooling still runs commands and evals outside the MCP.

See the detailed compatibility analysis:

• [Harness compatibility analysis - 2026-05-02](docs/harness-compatibility-analysis-2026-05-02.md)
• [Gradient Flow AgentOps synthesis - 2026-05-02](docs/gradient-flow-agentops-synthesis-2026-05-02.md)
• [Harness quality control - 2026-05-02](docs/harness-quality-control-2026-05-02.md)
• [Usage playbook](docs/usage-playbook.md)
• [Multi-client MCP setup](docs/multi-client-setup.md)
• [Harness engineering research notes](docs/harness-engineering-research-2026-05-01.md)
• [Marketing launch kit](docs/marketing-launch-kit.md)

Important operating principle: add harness structure only when it improves acceptance evidence, recovery, safety, or handoff quality. Verifiers, extra stages, and multi-candidate search are hypotheses to measure, not automatic wins.

The harness loop

User request
  -> query project knowledge
  -> create execution contract
  -> implement inside contract boundaries
  -> record traces, research, and lessons
  -> record verification evidence
  -> audit governance and stop on BLOCK
  -> export observability report when risk or uncertainty rises
  -> optionally record eval cases/runs for harness-profile changes
  -> record harness proposal and promotion decision when optimizing the harness
  -> export natural-language harness spec when sharing or porting the loop
  -> evaluate completion gate
  -> compact handoff context when needed

What gets written

The server creates a project-local .codex-harness/ directory. Typical files include:

.codex-harness/
  state.json
  policy.json
  HARNESS.md
  contracts/
  traces/
  gates/
  knowledge/
  evals/
  harness-profiles/
  harness-proposals/
  promotion-decisions/
  migrations/

This makes the agent's operating state inspectable in normal files rather than hidden in a chat transcript.

MCP surface

Tools

• harness_bootstrap
• harness_migrate
• harness_create_contract
• harness_update_state
• harness_record_trace
• harness_record_verification
• harness_record_harness_profile
• harness_list_harness_profiles
• harness_record_eval_case
• harness_list_eval_cases
• harness_record_eval_run
• harness_list_eval_runs
• harness_compare_eval_runs
• harness_record_harness_proposal
• harness_list_harness_proposals
• harness_record_promotion_decision
• harness_list_promotion_decisions
• harness_export_nl_harness
• harness_export_observability_report
• harness_write_governance_policy
• harness_audit_governance
• harness_export_governance_report
• harness_record_knowledge
• harness_record_research
• harness_record_lesson
• harness_query_knowledge
• harness_rebuild_knowledge_index
• harness_list_knowledge
• harness_next_step
• harness_eval_gate
• harness_compact_context
• harness_list

Resources

• harness://state
• harness://contracts
• harness://contract/{id}
• harness://traces/recent
• harness://gates/recent
• harness://governance/policy
• harness://governance/report
• harness://knowledge/index
• harness://knowledge/recent
• harness://knowledge/item/{id}
• harness://evals/cases
• harness://evals/runs
• harness://eval-case/{id}
• harness://eval-run/{id}
• harness://harness-profiles
• harness://harness-profile/{id}
• harness://harness-proposals
• harness://harness-proposal/{id}
• harness://promotion-decisions
• harness://promotion-decision/{id}
• harness://harness/spec
• harness://observability/report

Prompts

• harness_bootstrap_project
• harness_contract_from_request
• harness_failure_recovery
• harness_verify_and_close
• harness_handoff_context
• harness_deep_research
• harness_learn_from_implementation
• harness_query_knowledge
• harness_record_harness_profile
• harness_record_eval_case
• harness_record_eval_run
• harness_compare_eval_runs
• harness_propose_harness_change
• harness_record_promotion_decision
• harness_meta_harness_review
• harness_export_nl_harness
• harness_observability_review
• harness_governance_review

Local knowledge RAG

The knowledge store is intentionally simple and local. It writes sanitized JSON and Markdown under:

.codex-harness/knowledge/

Use it like this:

1. Query first with harness_query_knowledge.
2. If the answer is missing or stale, research normally with Codex web/GitHub tools.
3. Store useful findings with harness_record_research.
4. After implementation, store reusable lessons with harness_record_lesson.
5. Future sessions retrieve that knowledge before planning.

This is not a hosted vector database. It is a dependency-free lexical retrieval layer designed to be transparent, inspectable, and safe for local agent work.

Good examples to store:

• a useful implementation lesson from a failed fix
• an official documentation source used for a decision
• a project-specific convention that future sessions should reuse
• a known verification command and what it proves

Eval records and harness profiles

Use eval records when changing the harness itself:

1. Record the current profile with harness_record_harness_profile.
2. Record a task or failure as an eval case with harness_record_eval_case.
3. Run the eval outside the MCP.
4. Store the result with harness_record_eval_run.
5. Compare baseline and candidate runs with harness_compare_eval_runs.

This keeps the MCP safe: it stores scores, costs, token counts, traces, and regressions, but it does not execute benchmark commands or generated harness code.

Meta-Harness-lite promotion loop

Use proposal and promotion records when optimizing the harness itself:

1. Record baseline and candidate profiles.
2. Record optimization, holdout, or regression eval cases.
3. Run evals outside the MCP.
4. Store eval results with harness_record_eval_run.
5. Record the proposed harness change with harness_record_harness_proposal.
6. Promote, reject,

…

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: chapzin
• Source: chapzin/codex-harness-mcp
• License: MIT
• Homepage: https://skills.sh/chapzin/codex-harness-mcp/codex-harness-mcp

Install and usage instructions live in the source repository linked above.