MCP Connector

repo-harness ships an MCP server that gives ChatGPT and Codex read-only access to your registered repos — workflow files plus the repo tree, text search, and file contents — while writes stay scoped to workflow artifacts (plans, sprints, contracts, handoffs). ChatGPT connects over HTTP with OAuth through a public /mcp endpoint; Codex connects locally over stdio with no tunnel. The sidecar is not a remote coding agent — it prepares workflow artifacts for the local agent host.

Prerequisites

An adopted repo

Run from a repository that has already run repo-harness adopt. See Setup.

repo-harness on PATH

The repo-harness CLI must be installed and resolvable on your shell PATH.

ChatGPT Developer Mode

A ChatGPT workspace with access to Developer Mode and custom MCP Connectors.

A public /mcp endpoint

A stable public HTTPS /mcp URL for recurring ChatGPT use. Local Codex uses stdio with no tunnel.

1. Start the local MCP server

1. Launch the planner-profile server over HTTP on localhost:

   repo-harness mcp serve --repo . --transport http --host 127.0.0.1 --port 8765 --profile planner

2. Confirm it’s healthy:

   curl http://127.0.0.1:8765/health

3. Read the local OAuth passphrase — ChatGPT will ask for it during authorization:

   jq -r .passphrase .repo-harness/mcp.oauth.json

4. Smoke-test OAuth discovery:

   curl http://127.0.0.1:8765/.well-known/oauth-protected-resource/mcp

Keep the passphrase out of source control

.repo-harness/mcp.oauth.json is an ignored local file. Never commit the passphrase or paste it into issue trackers, PRs, or shared logs.

2. Choose a tunnel endpoint

ChatGPT needs a public HTTPS URL ending in /mcp. Prefer a stable hostname for recurring use — a quick tunnel’s URL changes, and ChatGPT treats each new URL as a different Connector app.

Stable (named)

cloudflared tunnel login
cloudflared tunnel create repo-harness-mcp
cloudflared tunnel route dns repo-harness-mcp repo-harness-mcp.example.com
cloudflared tunnel run --url http://127.0.0.1:8765 repo-harness-mcp

Then record the stable endpoint in ignored local config:

repo-harness mcp setup chatgpt --repo . --endpoint <https-url>/mcp

Quick (one-off)

cloudflared tunnel --url http://127.0.0.1:8765

Use the printed HTTPS URL with /mcp appended as your Connector URL:

<https-tunnel-url>/mcp

3. Create the ChatGPT Connector

1. Open ChatGPT Settings.
2. Enable Developer Mode if your workspace exposes it.
3. Go to Connectors.
4. Create a Connector named repo-harness.
5. Paste the HTTPS Connector URL ending in /mcp.
6. Configure Connector authentication as OAuth.
7. Click Scan Tools.
8. When the authorization page opens, enter the passphrase from .repo-harness/mcp.oauth.json.
9. Wait for the tool scan to finish, then create the Connector.
10. Keep write confirmations enabled.

4. Wire Codex (stdio)

Codex runs locally and needs no tunnel — it speaks stdio directly. Auto-generate the config:

repo-harness mcp setup codex --repo . --scope project

This writes .codex/config.toml with a stdio repo_harness server entry and the allowed tool list.

5. Dev-mode agent runner (opt-in)

Off by default — local only

The planner Connector does not run Codex or Claude. Only enable the dev runner if you intentionally want ChatGPT to trigger a local agent through MCP. Keep it behind local Developer Mode with per-call confirmations, and never expose an orchestrator tunnel to untrusted users.

repo-harness mcp serve --repo . --transport http --host 127.0.0.1 --port 8765 \
  --profile orchestrator --enable-dev-runner --dev-runner-agents codex

Or via environment override:

REPO_HARNESS_MCP_DEV_RUNNER=1 REPO_HARNESS_MCP_DEV_RUNNER_AGENTS=codex,claude \
  repo-harness mcp serve --repo . --transport http --profile orchestrator

When enabled, the server exposes run_agent_goal. It reads only .ai/harness/handoff/codex-goal.md and runs that fixed handoff through the allowed local CLI. It is not arbitrary shell.

What gets exposed

The planner profile is read-mostly: it can read your registered repos and write planning artifacts only — never application source, manifests, lockfiles, CI config, secrets, or files outside an allowed repo root.

• Workflow reads: harness_status, harness_doctor, read_workflow_file, list_workflow_files, latest_handoff, latest_checks
• Repo reads (read-only): reader_status, list_allowed_roots, open_workspace, tree, search_text, read_text — browse and search the repo, not just workflow files
• Planning writes: write_prd_from_idea, write_checklist_sprint, prepare_codex_goal_from_sprint

Deny globs stay active even with repo reads enabled: .env, private keys, SSH keys, credentials, secrets, .git, and dependency/build output are never returned.

Registered repos and multi-repo

One Connector can serve every repo you’ve adopted. repo-harness adopt and repo-harness init register a repo in ~/.repo-harness/registered-repos.json; discover_harness_repos lists them, and read tools accept a repo_path to target a specific one. Broad full-disk read is deprecated — legacy fullDiskRead: true now fails closed; add extra non-repo roots explicitly with --allow-root.

User-scope setup (repo-harness mcp setup chatgpt without --repo, storing config and auth under ~/.repo-harness/) works for Developer Mode deployments. HTTP auth supports OAuth — with offline_access refresh-token rotation — and a url-token compatibility mode.

The expected planning chain: idea → write_prd_from_idea → write_checklist_sprint → prepare_codex_goal_from_sprint → local Codex /goal execution.

Troubleshooting

• If ChatGPT cannot connect, verify the tunnel URL is HTTPS and ends in /mcp.
• If ChatGPT returns unauthorized, verify OAuth discovery works and re-run the passphrase flow.
• If tools are missing, restart repo-harness mcp serve and rescan tools.
• If writes fail, verify the target path is a PRD, sprint, plan, or approved handoff file.
• If ChatGPT generated prose instead of checklist Sprint task cards, ask it to use write_checklist_sprint.
• If Codex cannot see the server, run repo-harness mcp setup codex --repo . --scope project.

Next steps

ChatGPT Pro planner The plan-and-review workflow this sidecar unlocks.

ChatGPT browser engine Drive ChatGPT Web through Oracle — no API key.