omp-worker-mcp
This server lets an MCP client act as a supervisor that delegates hands-on coding work to local Oh My Pi (OMP) workers and reviews their structured results.
Run a single task —
omp_run_compactstarts one OMP job in a givencwdwith agoal, acceptance criteria, timeout and optional supervisor brief, waiting up to 60s for a compact result.Run a batch as a DAG —
omp_run_batch_compactexecutes up to 50 tasks with dependency ordering and 1–10 parallel workers, validating cycles and overlapping writeownershipbefore anything starts.Delegate asynchronously —
omp_delegatereturns ajob_idimmediately for low-level background work.Wait for completion —
omp_wait(jobs, ≤60s) andomp_wait_group(batches, ≤240s) poll until terminal status or timeout.Inspect full details —
omp_resultreturns status, attempt logs, paths, goal/cwd and the full final response when a compact summary isn't enough.Correct in place —
omp_continuesends targeted feedback to the same OMP session, bounded bymax_attempts(default 3).Stop work —
omp_cancelkills one job's process tree;omp_cancel_groupcancels every pending and running task in a batch.Get reviewable output — every result includes a summary, changed-file artifacts, verification evidence and remaining items, persisted on disk across server restarts.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@omp-worker-mcp Delegate a DAG workflow to extract and summarize all API endpoints in the codebase"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
omp-worker-mcp
Let your main AI agent plan and review — and hand the hands-on coding to local Oh My Pi workers.
An MCP server that turns ChatGPT, Codex, Claude Code, Cursor and other MCP clients into a supervisor, and Oh My Pi (OMP) on your own machine into its background workforce.
English · 简体中文 · Documentation
Quick start · Usage · Tools · Configuration · Safety model · FAQ
What it does
Most coding agents do everything in one place: read the code, plan, edit, run tests, fix — all inside one conversation and one model's budget. omp-worker-mcp splits that work into two roles:
Role | Who | Responsibility |
Supervisor | The agent you talk to: ChatGPT, Codex, Claude Code, Cursor… | Understands the request, splits the work, writes acceptance criteria, reviews the results |
Worker | The OMP CLI on your machine, using the model you picked in | Reads files, edits code, runs shell commands and tests, reports back |
omp-worker-mcp is the bridge between them. It gives the supervisor a small set of MCP tools, starts OMP in the background, keeps every job on disk, and returns a short structured report instead of a wall of logs.
Highlights
One task or a whole plan —
omp_run_compactdelegates a single task;omp_run_batch_compactruns up to 50 tasks as a dependency graph (DAG), up to 10 at a time.Declared write-scope validation — parallel write tasks in a batch must declare the paths they own; overlapping declared scopes and dependency cycles are rejected before any worker starts (a scheduling check and prompt constraint, not an OS filesystem lock).
Results you can review — every worker finishes with an
OMP_WORKER_RESULTenvelope: status, summary, changed files, verification evidence and remaining items.Correct instead of restart —
omp_continuesends feedback to the same OMP session, so the worker keeps its context.Persistent jobs — job records, logs and results live on disk and can still be read after the MCP server restarts.
Works from ChatGPT on the web — through OpenAI's Secure MCP Tunnel: no inbound port, plus an allowlist (
OMP_WORKER_ALLOWED_ROOTS, available since0.2.0; npm0.1.1lacks this feature) for the directories jobs may run in.
Related MCP server: claude-orchestrator
When to use it
A good fit when
you want a strong model to make the decisions while a faster or cheaper model does the typing;
the task is big enough to hand off: a feature, a bug fix with tests, a multi-module refactor, a long read-only investigation;
you want several parts of a repo worked on in parallel without agents overwriting each other;
you think with ChatGPT and want it to act on files on your own machine.
Probably not worth it when
the change is one line or the question is quick — the supervisor's own tools are faster;
you need a real OS-level sandbox. This project controls where jobs start and what they are told to touch, not what OMP is technically able to do (see Safety model).
Quick start
You need: Node.js ≥ 22 · Oh My Pi installed · an MCP client (Codex, Claude Code, Cursor, ChatGPT, …).
1. Install and set up OMP
Install OMP by following its official instructions, then:
omp --version # confirm the CLI is on your PATH
omp setup # sign in and choose the default modelThe default model you pick here is the model every worker will use. (Advanced: set modelRoles.default: <provider>/<model> in ~/.omp/agent/config.yml.)
If
ompis not on yourPATH, setOMP_WORKER_OMP_COMMANDto the full path of the executable in the MCP config below.
2. Register the MCP server in your client
There is nothing to install globally — the client runs the published package with npx -y omp-worker-mcp. Pick your client:
Edit ~/.codex/config.toml (Windows: C:\Users\<you>\.codex\config.toml):
[mcp_servers.omp-worker]
command = "npx"
args = ["-y", "omp-worker-mcp"]
[mcp_servers.omp-worker.env]
OMP_WORKER_OMP_COMMAND = "omp"
# Optional (Codex Code Mode only): let Codex call omp-worker tools directly
# without code-mode wrapping. Per the current Codex config reference, merge into
# your existing [features.code_mode] table (do not create a duplicate table header)
# and append "mcp__omp_worker" while preserving any other list entries:
[features.code_mode]
direct_only_tool_namespaces = ["mcp__omp_worker"](If [features.code_mode] already exists in your config.toml, merge into that table and append "mcp__omp_worker" to direct_only_tool_namespaces rather than duplicating the table or overwriting existing entries. Legacy Codex builds used a top-level direct_only_tool_namespaces = ["mcp__omp_worker"] key before any [table] header. Neither setting is required to register the MCP server; see Codex direct namespace setup and the official Codex Config Reference.)
Version requirement (
>= 0.2.0):OMP_WORKER_ALLOWED_ROOTSis available sinceomp-worker-mcp0.2.0(historical npm0.1.1lacks this feature and does not enforceOMP_WORKER_ALLOWED_ROOTS). Confirmnpx -y omp-worker-mcp@latest --versionreports0.2.0or newer before exposing local execution remotely.
Run the server locally behind OpenAI's tunnel-client; your machine only makes outbound connections.
export OMP_WORKER_OMP_COMMAND=omp
export OMP_WORKER_ALLOWED_ROOTS='["/Users/you/Projects"]' # strongly recommended for remote access (available since 0.2.0; 0.1.1 lacks this feature)
export CONTROL_PLANE_API_KEY='<runtime-api-key>'
tunnel-client init \
--sample sample_mcp_stdio_local \
--profile omp-worker \
--tunnel-id <your-tunnel-id> \
--mcp-command "npx -y omp-worker-mcp"
tunnel-client doctor --profile omp-worker --explain
tunnel-client run --profile omp-workerWindows PowerShell commands, 0.1.1 upgrade / local-build notes, managed runtime alternatives (tunnel-client runtimes connect), permission requirements and the full trust boundary: ChatGPT Secure MCP Tunnel guide.
claude mcp add omp-worker --scope user --env OMP_WORKER_OMP_COMMAND=omp -- npx -y omp-worker-mcpUse --scope project to register it for the current project only. On Windows cmd.exe, if npx fails to resolve, use cmd /c npx.
{
"mcpServers": {
"omp-worker": {
"command": "npx",
"args": ["-y", "omp-worker-mcp"],
"env": {
"OMP_WORKER_OMP_COMMAND": "omp"
}
}
}
}File locations and client-specific notes: Client configurations.
Restart the client after changing its config.
3. Tell your agent when to delegate
Registering the server makes the tools available; it does not make the agent choose them. Add a short policy to your project's instruction file — AGENTS.md (Codex), CLAUDE.md (Claude Code), .cursorrules / .github/copilot-instructions.md (others) — or to ChatGPT's project instructions:
## Delegation policy (omp-worker-mcp)
- Quick questions, single-file edits, design discussion: do it yourself.
- Substantive single tasks (feature, bug fix, refactor, long investigation): inspect briefly,
then delegate with `omp_run_compact`, giving a clear `goal` and `acceptance` criteria.
- Multi-part work: use `omp_run_batch_compact`. Parallel write tasks need disjoint `ownership`;
tasks touching the same files must be ordered with `depends_on`.
- Review every result. If acceptance is not met, use `omp_continue` with specific feedback.
- Never delegate `git push`, publishing, deployments or secret changes — confirm those with the user.A fuller template: Author workflow → Policy template.
4. Run your first task
Start with something read-only:
Use omp-worker-mcp to do a read-only inspection of this workspace: summarize the
project structure and dependencies. Do not modify any files.What you should see: the agent calls omp_run_compact, OMP works in the background, and a short summary comes back with no files changed. If the job runs longer than the wait window (60 s by default), the call returns a job_id with status running and the agent keeps going with omp_wait — that is normal.
Usage
Once the policy is in place you can just describe the outcome you want. The examples below show what the supervisor sends under the hood.
A single task
"Add exponential backoff to the HTTP client in
src/net/, cover it with unit tests, and make surenpm testpasses."
// omp_run_compact
{
"cwd": "/path/to/repo",
"goal": "Add exponential backoff (max 5 retries) to src/net/client.ts for 5xx and network errors.",
"acceptance": [
"Unit tests cover the retry and give-up paths",
"npm test passes"
],
"timeout_minutes": 30
}What comes back is compact (abridged example):
{
"job_id": "job-…",
"status": "completed",
"attempt": 1,
"max_attempts": 3,
"session_id": "sess-…",
"summary": "Added retry with exponential backoff to the HTTP client.",
"artifacts": [
{ "path": "src/net/client.ts", "description": "retry loop + backoff helper" },
{ "path": "test/net/client.test.ts", "description": "retry / give-up tests" }
],
"verification": ["npm test: all tests passed"],
"remaining": [],
"details_path": "…/jobs/job-…/job.json"
}Several tasks as a DAG
"Add a
/healthendpoint to the API and a status badge to the UI in parallel, then add an integration test that covers both."
graph LR
api["api · write src/api/"] --> tests["tests · write tests/"]
ui["ui · write src/ui/"] --> tests// omp_run_batch_compact
{
"cwd": "/path/to/repo",
"max_parallel": 2,
"tasks": [
{ "id": "api", "goal": "Add GET /health returning build info.", "access": "write", "ownership": ["src/api/"] },
{ "id": "ui", "goal": "Show a status badge fed by /health.", "access": "write", "ownership": ["src/ui/"] },
{ "id": "tests", "goal": "Add an integration test for /health and the badge.",
"depends_on": ["api", "ui"], "access": "write", "ownership": ["tests/"],
"acceptance": ["npm test passes"] }
]
}Rules worth knowing:
writetasks must list the paths they own inownership(relative tocwd);read_onlytasks list none.Two tasks that may run at the same time cannot own overlapping paths — order them with
depends_oninstead.max_parallelis 1–10 (default 4); the whole group has a deadline (group_timeout_minutes, default 60).If the group is still running when the wait window ends, you get a
group_id; continue withomp_wait_group.
Supervising a job
Situation | Tool |
Still running |
|
Need logs, attempts or the full final answer |
|
Result doesn't meet acceptance |
|
Wrong direction, stop it |
|
Tools
Tool | Kind | What it does |
| Recommended | Start one task and wait up to |
| Recommended | Validate and run a DAG of up to 50 tasks; wait up to |
| Low-level | Start one task and return a |
| Low-level | Wait for a job to finish |
| Low-level | Wait for a batch group to finish |
| Inspect | Full status, attempts, |
| Supervise | Send feedback to the same OMP session for another attempt |
| Control | Stop a job and its process tree |
| Control | Stop every pending and running task in a group |
Full parameters and limits: Tool reference.
Configuration
Everything is configured through environment variables, set in the client's MCP config (env) or in the shell that launches the server.
Variable | Default | Purpose |
|
| OMP executable name or full path |
| (unset = no restriction) | JSON array of absolute directories that jobs must run inside. Set this for any remote use. (Available since |
|
| Where job state, prompts and logs are stored (the default path is used even if you don't use Codex) |
| (unset = keep forever) | Delete finished records older than N seconds |
| (unset = no limit) | Delete the oldest finished records once the store exceeds N bytes |
All variables, the on-disk layout and restart behaviour: Operations · .env.example.
Safety model
What omp-worker-mcp enforces
With
OMP_WORKER_ALLOWED_ROOTSset (available since0.2.0; npm0.1.1lacks this feature), a job'scwdmust resolve (viarealpath) inside an approved root. Sibling-prefix tricks and symlink/junction escapes are rejected before OMP starts; a present-but-invalid value fails closed.In a batch, parallel
writetasks must have disjointownership, and the graph must be acyclic — checked before any worker is spawned.Ownership and read-only intent are passed to each worker as explicit constraints.
What it does not do
It is not a sandbox. OMP and anything it runs have the same permissions as the user account that started the server. Ownership is a scheduling check plus an instruction to the worker, not a filesystem lock.
It does not decide what is safe to run. Keep
git push, publishing, deployments and secret changes with you and the supervisor.
For remote access (e.g. ChatGPT via Secure MCP Tunnel), always set OMP_WORKER_ALLOWED_ROOTS, and consider a dedicated low-privilege account, a container or a VM. To report a vulnerability, see SECURITY.md.
Platform support
Platform | Status |
Windows | ✅ Verified end-to-end with the real OMP CLI and in CI ( |
macOS | 🟡 Full test suite runs in CI ( |
Linux | 🟡 Full test suite runs in CI ( |
Client | Status |
Codex | ✅ Used daily by the author |
ChatGPT web (Secure MCP Tunnel) | 📄 Documented workflow — see the guide |
Claude Code, Cursor, VS Code / Copilot, Windsurf, Continue | 📄 Documented configurations, not integration-tested in CI |
Cloud / remote agent hosts | ⚠️ Only if they provide Node.js ≥ 22, OMP on |
Linux reports and client configs that you have verified are very welcome — see Contributing.
FAQ
Tools being available doesn't mean they get chosen. Add the delegation policy from step 3, or name the server explicitly in your prompt ("use omp-worker-mcp to…"). On Codex with Code Mode enabled, you can also optionally configure features.code_mode.direct_only_tool_namespaces.
The MCP server can't find OMP. Set OMP_WORKER_OMP_COMMAND to the full path of the executable — GUI clients often start with a shorter PATH than your terminal.
Expected for longer tasks: the call only waits up to wait_seconds. The job keeps running in the background; call omp_wait (or omp_wait_group) to keep waiting.
OMP's default model — the one chosen in omp setup (or modelRoles.default in ~/.omp/agent/config.yml). The supervisor's model is whatever your client uses. That's the point: they can be different.
The task's cwd is not inside any approved root. This is the allowlist working; add the directory to OMP_WORKER_ALLOWED_ROOTS if it should be allowed (note: OMP_WORKER_ALLOWED_ROOTS is available since 0.2.0; npm 0.1.1 lacks this feature).
Two tasks that could run at the same time own overlapping paths. Give them separate ownership scopes, or add depends_on so one runs after the other.
The worker is a separate agent (OMP) with its own model and provider, runs in the background across conversation turns, keeps its state on disk, and can be driven by any MCP client — including ChatGPT on the web. Batches add dependency ordering and write-scope checks on top.
Documentation
Guide | Read it when you want to… |
Set up the delegation policy and understand the supervise → review → correct loop | |
Configure Codex, Claude Code, Cursor, VS Code, Windsurf or Continue | |
Drive local OMP from ChatGPT on the web | |
See every tool, parameter and the result envelope | |
Tune environment variables, storage, retention and restarts | |
Compare direct execution with supervisor–worker delegation | |
Release to npm and the Official MCP Registry (maintainers) |
COMPATIBILITY.md defines the public contract and versioning policy; CHANGELOG.md lists releases.
Contributing
Issues and pull requests are welcome — especially Linux verification and tested client configs. Start with CONTRIBUTING.md. To build from source:
git clone https://github.com/divenire990/omp-worker-mcp.git
cd omp-worker-mcp
npm ci
npm test # builds, then runs the test suite against a fake OMPAcknowledgements
Built on the Model Context Protocol TypeScript SDK and designed around Oh My Pi (MIT). OMP is not bundled and must be installed separately. This project is independent and not affiliated with OMP, OpenAI or Anthropic.
License
Available Tools
9 toolsomp_cancelStop OMP TaskADestructiveIdempotent
Request immediate cancellation of one exact delegated OMP job. The detached runner owns the OMP child PID and terminates that process tree safely. Call this immediately when the user asks to stop; do not inspect PIDs or manually kill processes first.
Inputs: job_id (required), reason. Returns: error, job_id, status, attempt, +7 more
omp_cancel_groupCancel Batch Task GroupADestructiveIdempotent
Request immediate cancellation of a running batch task group and its child tasks. Writes a cancellation request that the detached group coordinator handles safely. Call this immediately when the user asks to stop a batch.
Inputs: group_id (required), reason. Returns: tasks, status, summary, group_id, +6 more
omp_continueSend Supervisory Feedback to Same OMP SessionADestructive
Resume the same OMP session with targeted supervisory feedback to correct specific acceptance defects without starting a fresh task from scratch. Bounded to remaining attempts within max_attempts.
Inputs: job_id (required), feedback (required), timeout_minutes. Returns: error, job_id, status, attempt, +7 more
omp_delegateDelegate Complete Task to OMP (Low-level)ADestructive
Low-level background delegation entrypoint. Transfers ownership of an execution task to OMP and returns immediately with job_id. Prefer omp_run_compact for standard workflows to avoid separate delegate/wait round trips.
Inputs: cwd (required), goal (required), acceptance, max_attempts, +2 more. Returns: error, job_id, status, attempt, +7 more
omp_resultInspect Complete OMP Task ResultARead-onlyIdempotent
Retrieve full details of a terminal OMP job, including finalResponse and attempt logs. Call this only when minimal acceptance check fails, high-risk operations occurred, or the user explicitly asks for full inspection; do not call this after every successful compact run.
Inputs: job_id (required). Returns: cwd, goal, error, job_id, +11 more
omp_run_batch_compactRun Batch OMP Tasks with DAG and Compact Aggregated Result (Preferred for Multi-task)ADestructive
Submits a decomposed group of OMP tasks to execute concurrently in the server-side bounded rolling pool (max_parallel 1-10) using a detached group runner. Enforces dependency DAG and write-ownership safety, waits up to wait_seconds (0-240, default 60s) for batch completion, and returns stable compact aggregated results. If still running when deadline elapses, returns group_id and minimal progress counts for subsequent omp_wait_group.
Inputs: cwd (required), tasks (required), max_parallel, wait_seconds, +4 more. Returns: tasks, status, summary, group_id, +6 more
omp_run_compactRun OMP Task with Compact Result (Preferred for Single Task)ADestructive
Preferred entrypoint for single substantive execution tasks. Creates a delegated OMP task, launches the detached runner, and waits up to wait_seconds (default 60s) for completion in a single MCP call. If finished, returns a compact summary, artifacts, verification, and details_path without dumping the full final response. If still running at the deadline, returns job_id and status running for subsequent omp_wait.
Inputs: cwd (required), goal (required), acceptance, max_attempts, +3 more. Returns: error, job_id, status, attempt, +7 more
omp_waitWait for OMP TaskARead-onlyIdempotent
Wait for an existing OMP job to reach a terminal status, polling up to wait_seconds (default 30s, max 60s). Returns the current status and summary once terminal or when the wait deadline elapses. Avoid polling in a tight loop.
Inputs: job_id (required), wait_seconds. Returns: error, job_id, status, attempt, +7 more
omp_wait_groupWait for Batch Task GroupARead-onlyIdempotent
Wait for an existing OMP task group to reach a terminal status, polling up to wait_seconds (0-240, default 60s). If completed, returns full aggregated compact results in original input order. If still running when deadline elapses, returns minimal progress counts without leaking task summaries.
Inputs: group_id (required), wait_seconds. Returns: tasks, status, summary, group_id, +6 more
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 9 tools
Each tool has a clearly distinct purpose: batch vs single, delegate vs wait vs cancel vs result retrieval vs continue. No two tools overlap in function—omp_run_compact and omp_delegate differ by synchronous vs asynchronous, and omp_wait_group vs omp_wait serve batch vs single jobs.
All tools follow a consistent `omp_<verb>[_<noun>]` pattern where the verb describes the action (run, wait, cancel, result, continue) and optional noun specifies the target (batch, group, compact). Perfectly predictable and uniform.
9 tools precisely cover the lifecycle of both single and batch task execution: submission, waiting, cancellation, result retrieval, and continuation. No tool is superfluous, and the count is tight for the complexity of the domain.
The tool surface covers every stage of task management: submission (run/delegate), monitoring (wait), cancellation (cancel), post-hoc inspection (result), and iterative correction (continue). No obvious gaps—both single and batch workflows are fully supported.
Maintenance
Related MCP Connectors
- aXDeprecatedio.github.ax-platform
Agent-native collaboration network: orchestrate a team of long-running agents from any MCP client.
Task manager for AI agents. Orchestrate agents to achieve large goals in unified control plane.
AI work orchestration for plans, tasks, teams, and coding-agent dispatch.
Design, build and run teams of AI agents with checked handoffs between them.
Related MCP Servers
- AlicenseAqualityAmaintenanceEnables orchestrating external AI-agent CLIs like Codex to execute project development tasks through an async task system with objective verification and automated failure rework loops.8182 npm11Apache 2.0
- AlicenseAqualityBmaintenanceEnables Cursor's main agent to delegate development tasks to Claude CLI subagents via MCP, supporting synchronous, asynchronous, and parallel task execution with monitoring and control.7ISC
- AlicenseCqualityBmaintenanceEnables multiple CLI-based AI agents to collaborate as a coordinated team through shared task queues, shared memory, and a message bus, with DAG orchestration, rate-limit avoidance, parallel dispatching, and long-task management.633MIT
- FlicenseNot gradedqualityAmaintenanceEnables a primary AI assistant to delegate tasks in parallel to specialized local CLI-based AI sub-agents, share project context, and synthesize their responses through a single MCP interface.-