MCP Orchestrator

Coordinate AI agents and MCP (Model Context Protocol) servers in a two-stage workflow: gather and process context with one model, then execute with another.

The orchestrator runs in two modes:

• Cursor mode (default, no API keys) — gathers context from your MCP servers and writes a Composer-ready Markdown workflow file you can paste straight into Cursor.
• API mode — runs the full pipeline end-to-end using an OpenAI-compatible model for context processing and Anthropic Claude for execution.

Architecture

                        User Task
                            │
                            ▼
                   ┌─────────────────┐
                   │  MCPOrchestrator │
                   └─────────────────┘
                            │
        ┌───────────────────┴────────────────────┐
        ▼                                        ▼
┌────────────────────┐                 ┌──────────────────────┐
│ Stage 1            │                 │ Stage 2              │
│ Context processing │ ──── plan ────► │ Task execution       │
│ (OpenAI-compatible)│                 │ (Anthropic Claude)   │
└────────────────────┘                 └──────────────────────┘
        ▲
        │ context
┌──────────────────────────────────────────────┐
│ MCP servers: sequential-thinking, context7,  │
│              puppeteer, memory, …            │
└──────────────────────────────────────────────┘

Requirements

• Python 3.10+
• Node.js 18+ (only for the optional TypeScript MCP server wrapper)
• An mcp.json configured in ~/.cursor/mcp.json (or pass --mcp-config)

Install

git clone https://github.com/Edx0n/mcp-orchestrator.git
cd mcp-orchestrator
pip install -r requirements.txt

Or as a package:

pip install -e .

Usage

Cursor mode (no API keys)

python cli.py "Analyze the MCP ecosystem and outline a developer guide"

Workflow files are written to _cursor_workflows/. Open the *_complete.md file, paste it into Cursor Composer (Ctrl+I / Cmd+I), switch to Max Mode for stage 1, then run the resulting plan.

API mode

cp .env.example .env
# fill in OPENAI_API_KEY and ANTHROPIC_API_KEY

python cli.py --mode api "Summarize current trends in AI"

--mode auto (the default) picks api if both keys are set, otherwise cursor.

As a library

import asyncio
from orchestrator import CursorMCPOrchestrator

async def main():
    orch = CursorMCPOrchestrator(output_dir="_cursor_workflows")
    result = await orch.execute_with_cursor(
        task="Build a weekly digest of new MCP servers",
        use_memory=True,
    )
    print(result.result)
    await orch.close()

asyncio.run(main())

For full API-mode usage:

from orchestrator import MCPOrchestrator, WorkflowConfig

config = WorkflowConfig(
    context_mcps=["sequential-thinking", "context7", "memory"],
    composer_model="gpt-4o",
    executor_model="claude-sonnet-4-5",
)
orch = MCPOrchestrator(workflow_config=config)
result = await orch.execute(task="…")

See examples/ for runnable scripts.

CLI options

mcp-orchestrator <task>
  --mode {auto,cursor,api}     orchestrator mode (default: auto)
  --mcp-config PATH            path to mcp.json (default: ~/.cursor/mcp.json)
  --output-dir DIR             cursor mode output dir (default: _cursor_workflows)
  --no-memory                  disable the memory MCP
  --no-save                    don't persist context to memory MCP (api mode)
  --log-level {DEBUG,INFO,WARNING,ERROR}

MCP server wrapper (optional)

mcp_server/ exposes the orchestrator as an MCP server itself, so it can be called from any MCP client (Cursor, Claude Desktop, …).

cd mcp_server
npm install
npm run build

Then add it to your mcp.json:

{
  "mcpServers": {
    "mcp-orchestrator": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-orchestrator/mcp_server/dist/index.js"]
    }
  }
}

Available tools: orchestrate_task, gather_context, list_mcp_servers, create_workflow.

Project layout

mcp-orchestrator/
├── cli.py                     CLI entry point
├── orchestrator/              Python package
│   ├── ai_agents.py           OpenAI + Anthropic clients
│   ├── core.py                MCPOrchestrator (API mode)
│   ├── core_cursor.py         CursorMCPOrchestrator (Cursor mode)
│   ├── cursor_agent.py        Composer file writer
│   ├── mcp_client.py          MCP stdio client
│   ├── workflows.py           Pydantic config + result models
│   └── utils.py
├── mcp_server/                TypeScript MCP server wrapper
├── examples/                  Runnable example scripts
├── tests/                     pytest suite
├── pyproject.toml
└── requirements.txt

Development

pip install -e ".[dev]"
pytest
ruff check .

License

MIT — see LICENSE.