Model Context Protocol (MCP) System
Relevant source files
The following files were used as context for generating this wiki page:
The Model Context Protocol (MCP) System within OhMyOpenCode provides a structured framework for AI agents to interact with the codebase, external documentation, and specialized reasoning subagents. It facilitates a multi-agent orchestration environment where different "Titans" (specialized agents) perform specific roles—such as planning, executing, reviewing, or consulting—to ensure high-quality software engineering outcomes.
The system is designed around "decision-complete" planning and rigorous verification. It utilizes a hierarchical agent structure where a lead orchestrator (Atlas) coordinates work plans generated by a strategist (Prometheus), which are then executed by a worker (Sisyphus) and reviewed by specialized evaluators (Momus and Oracle).
Sources: src/agents/prometheus/gpt.ts:21-30, src/agents/atlas/gpt-prompt-sections.ts:1-6, src/agents/sisyphus/default.ts:167-175
Agent Architecture and Roles
The system employs a delegation-heavy architecture where the primary agent acts as a conductor rather than an implementer. Each agent is governed by strict identity constraints and technical scopes.
Core Agent Personas
| Agent | Role | Primary Responsibility |
|---|---|---|
| Prometheus | Strategic Planner | Generates "decision-complete" work plans; forbidden from writing code. |
| Atlas | Master Orchestrator | Conducts the execution of plans by delegating tasks to subagents. |
| Sisyphus | Worker/Executor | Performs the actual implementation and code modification tasks. |
| Momus | Plan Reviewer | Ruthlessly audits work plans for executability and valid references. |
| Oracle | Strategic Advisor | Provides high-level architectural consultation and complex debugging support. |
Sources: src/agents/prometheus/identity-constraints.ts:10-25, src/agents/atlas/gpt-prompt-sections.ts:1-6, src/agents/sisyphus/default.ts:167-180, src/agents/momus.ts:25-30, src/agents/oracle.ts:44-50
Orchestration Flow
The interaction between agents follows a strict lifecycle from requirements gathering to final verification.
The diagram shows the sequential flow from a user request through planning, review, and execution phases.
Sources: src/agents/prometheus/gpt.ts:75-150, src/agents/atlas/gpt-prompt-sections.ts:55-140, src/agents/momus.ts:110-120
Planning and Strategy (Prometheus)
Prometheus is the entry point for complex requests. Its fundamental constraint is that it cannot write code; it only writes Markdown files within the .sisyphus/ directory.
Decision-Complete Principle
A plan is considered "decision-complete" when the implementer needs zero judgment calls. Every ambiguity must be resolved, and every pattern reference must be provided before implementation begins.
The Three Principles of Prometheus
- Decision Complete: Leave zero decisions to the implementer.
- Explore Before Asking: Ground questions in the environment by running targeted searches first.
- Two Kinds of Unknowns: Differentiate between discoverable facts (repo truth) and preferences (user intent).
Sources: src/agents/prometheus/gpt.ts:33-47, src/agents/prometheus/identity-constraints.ts:110-120
Plan Artifacts
Plans are saved to .sisyphus/plans/*.md and drafts to .sisyphus/drafts/*.md. The system enforces strict path discipline; writing outside these paths is blocked by system hooks.
Sources: src/agents/prometheus/identity-constraints.ts:88-100
Execution and Task Management (Sisyphus & Atlas)
Once a plan is approved, Atlas orchestrates its completion using Sisyphus or specialized subagents.
Task Discipline
Multi-step work is managed through a strict TodoWrite or TaskCreate workflow. Agents must:
- Register: Create atomic steps immediately on receiving a request.
- In-Progress: Mark only one task as
in_progressat a time. - Complete: Mark tasks
completedimmediately after verification.
Sources: src/agents/sisyphus/default.ts:26-40, src/agents/atlas/gpt-prompt-sections.ts:57-65
Verification: 4-Phase QA Protocol
Atlas enforces a non-negotiable verification sequence for every delegated task:
- Phase 1: Read Code: Inspect
git diffandReadevery changed file to catch "lies" or scope creep. - Phase 2: Automated Verification: Run
lsp_diagnostics, targeted tests, and full builds. - Phase 3: Hands-on QA: Manually test the feature (Playwright for UI, Curl for APIs, Bash for CLI).
- Phase 4: Gate Decision: Final approval based on whether the agent can explain every line and saw it work.
Sources: src/agents/atlas/gpt-prompt-sections.ts:100-145
Specialized Consultation Agents
The system leverages specialized agents for high-risk or specific technical scenarios.
Oracle (Architecture & Debugging)
Oracle is an "expensive" high-IQ reasoning specialist used for:
- Multi-system architecture trade-offs.
- Hard debugging after 2+ failed fix attempts.
- Security and performance concerns.
Sources: src/agents/oracle.ts:14-25
Momus (Plan Review)
Momus acts as a "blocker-finder" rather than a perfectionist. It validates that:
- Referenced files and line numbers actually exist.
- Tasks have sufficient starting context.
- QA scenarios are executable and concrete.
Sources: src/agents/momus.ts:40-65
Subagent Dispatch Mechanism
Agents use a task() function to spawn subagents, supporting background execution and session persistence.
task(
subagent_type="explore",
load_skills=[],
run_in_background=true,
prompt="[CONTEXT]: ... [GOAL]: ... [REQUEST]: ..."
)
Sources: src/agents/prometheus/gpt.ts:80-90, src/agents/sisyphus/default.ts:235-245
System Constraints and Implementation Rules
| Rule | Description | File Reference |
|---|---|---|
| Markdown Only | Prometheus can only write .md files in .sisyphus/. | identity-constraints.ts:85 |
| Single Plan Mandate | All tasks for a request must exist in ONE plan file. | identity-constraints.ts:135 |
| Incremental Write | Large plans must use skeleton Write + batch Edit to avoid token limits. | identity-constraints.ts:160 |
| Anti-Duplication | Agents must check existing context before re-exploring. | prometheus/gpt.ts:31 |
| Session Continuity | Use session_id for retries to preserve subagent context. | sisyphus/default.ts:300-310 |
Summary
The MCP System is a sophisticated multi-agent orchestration layer that prioritizes planning quality and verification over immediate implementation. By separating the concerns of planning (Prometheus), orchestration (Atlas), and execution (Sisyphus), the project ensures that code changes are consistent with existing patterns and verified through a rigorous 4-phase protocol. The inclusion of advisor agents like Oracle and reviewers like Momus provides a safety net for complex architectural decisions and prevents implementation stalls due to vague requirements.