Skip to content

multi-client-setup.md

Latest commit

 

History

History
270 lines (206 loc) · 6.51 KB

multi-client-setup.md

File metadata and controls

270 lines (206 loc) · 6.51 KB
Raw

Multi-Client MCP Setup

codex-harness-mcp is a local stdio MCP server. The server process is always the same:

node <installed-codex-harness-mcp>/src/server.mjs

The difference between clients is only the configuration file shape. The installer can now copy the local dependency-free server and write the right config for the major MCP-capable coding clients.

Quick install

Codex only:

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

All supported clients:

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

Selected clients:

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

List supported clients:

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

Scope behavior

--scope auto is the safest default for broad compatibility:

  • project config where the client has a stable project file
  • global config for clients whose MCP config is global-only in practice
  • Codex still writes to CODEX_HOME or ~/.codex/config.toml

Project-scoped files written by --scope auto:

Client File
Claude Code .mcp.json
OpenCode opencode.json
Kilo CLI / Kilo Code .kilo/kilo.jsonc
Gemini CLI .gemini/settings.json
Cursor .cursor/mcp.json
VS Code / GitHub Copilot .vscode/mcp.json
Roo Code .roo/mcp.json

Global-scoped files written by --scope auto:

Client File
Cline ~/.cline/data/settings/cline_mcp_settings.json
Windsurf Cascade ~/.codeium/windsurf/mcp_config.json

Clients with known global paths can also use --scope global:

node scripts/install-codex-harness-mcp.mjs --clients opencode,kilo,gemini,cursor,cline,windsurf --scope global

Known global files:

Client File
OpenCode ~/.config/opencode/opencode.json
Kilo CLI / Kilo Code ~/.config/kilo/kilo.jsonc
Gemini CLI ~/.gemini/settings.json
Cursor ~/.cursor/mcp.json
Cline ~/.cline/data/settings/cline_mcp_settings.json
Windsurf Cascade ~/.codeium/windsurf/mcp_config.json

Roo Code note: Roo project config is emitted as a best-effort compatibility target because .roo/mcp.json is widely used by Roo MCP integrations. The official Roo Code docs currently announce that Roo Code products shut down on May 15, 2026, so treat it as migration support rather than the strongest long-term target.

Generated config shapes

Claude Code

Claude Code project config uses .mcp.json:

{
  "mcpServers": {
    "codex-harness": {
      "type": "stdio",
      "command": "node",
      "args": ["C:/Users/you/.codex/mcp-servers/codex-harness-mcp/src/server.mjs"]
    }
  }
}

For user/global Claude Code config, use Claude Code's own command because it stores user scope internally:

claude mcp add --transport stdio codex-harness -- node C:/Users/you/.codex/mcp-servers/codex-harness-mcp/src/server.mjs

OpenCode

OpenCode uses an mcp object:

{
  "mcp": {
    "codex-harness": {
      "type": "local",
      "command": ["node", "C:/Users/you/.codex/mcp-servers/codex-harness-mcp/src/server.mjs"],
      "enabled": true
    }
  }
}

Kilo CLI / Kilo Code

Kilo uses the same local MCP shape as OpenCode:

{
  "mcp": {
    "codex-harness": {
      "type": "local",
      "command": ["node", "C:/Users/you/.codex/mcp-servers/codex-harness-mcp/src/server.mjs"],
      "enabled": true
    }
  }
}

Gemini CLI

Gemini CLI uses mcpServers in settings.json:

{
  "mcpServers": {
    "codex-harness": {
      "command": "node",
      "args": ["C:/Users/you/.codex/mcp-servers/codex-harness-mcp/src/server.mjs"],
      "timeout": 30000,
      "trust": false
    }
  }
}

Cursor

Cursor uses .cursor/mcp.json or ~/.cursor/mcp.json:

{
  "mcpServers": {
    "codex-harness": {
      "command": "node",
      "args": ["C:/Users/you/.codex/mcp-servers/codex-harness-mcp/src/server.mjs"]
    }
  }
}

VS Code / GitHub Copilot

VS Code uses .vscode/mcp.json with a servers object:

{
  "servers": {
    "codexHarness": {
      "type": "stdio",
      "command": "node",
      "args": ["C:/Users/you/.codex/mcp-servers/codex-harness-mcp/src/server.mjs"]
    }
  }
}

Cline

Cline uses cline_mcp_settings.json:

{
  "mcpServers": {
    "codex-harness": {
      "command": "node",
      "args": ["C:/Users/you/.codex/mcp-servers/codex-harness-mcp/src/server.mjs"]
    }
  }
}

Windsurf Cascade

Windsurf uses mcp_config.json:

{
  "mcpServers": {
    "codex-harness": {
      "command": "node",
      "args": ["C:/Users/you/.codex/mcp-servers/codex-harness-mcp/src/server.mjs"]
    }
  }
}

Roo Code

Roo Code project config uses .roo/mcp.json:

{
  "mcpServers": {
    "codex-harness": {
      "command": "node",
      "args": ["C:/Users/you/.codex/mcp-servers/codex-harness-mcp/src/server.mjs"]
    }
  }
}

Why this helps adoption

Different agents now get the same harness surface:

  • contracts
  • local knowledge/RAG
  • traces
  • verification evidence
  • observability reports
  • eval records
  • harness proposals
  • promotion decisions
  • natural-language harness spec
  • completion gates

This turns codex-harness-mcp from a Codex-only helper into a portable local harness for the broader MCP coding-agent ecosystem.

Security notes

The multi-client installer still does not execute external client CLIs. It only:

  1. copies the bundled dependency-free local MCP server
  2. writes or merges JSON/TOML config files
  3. points clients at the local node .../server.mjs command

It does not download packages, run package managers, invoke shells, browse the web, call remote services, or handle credentials.

Source references