Skip to content

For developers

Plug your agents into the same graph as your plans

Project Orchestrator exposes everything the app does as MCP tools, a REST API and four WebSocket streams. A Rust server keeps code, plans, decisions and notes in a Neo4j graph and in Meilisearch.

MCP tools
33
MCP tools
actions across them
426
actions across them
languages parsed
17
languages parsed
WebSocket streams
4
WebSocket streams

Looking for the product itself? Go back to the home page.

project(action: "sync", slug: "my-app")

code(
  action: "analyze_impact",
  target: "src/session.rs",
  project_slug: "my-app"
)

plan(action: "run", plan_id: "<uuid>")

Connect

Plug PO into an MCP client

The desktop app or the server must be running. Then one command registers PO in Claude Code, or you add the entry by hand for any other MCP client.

Install and start the server

The server needs Neo4j and Meilisearch. NATS is optional. The repository ships a docker-compose.yml for all three.

orchestrator serve

# needs Neo4j and Meilisearch: docker compose up -dbrew install this-rs/tap/project-orchestratororchestrator serve --port 8080

Register PO in Claude Code

This writes the MCP entry in stdio mode, with this server URL and its auth secret, and pre-approves the tools.

orchestrator setup-claude

orchestrator setup-claude --port 8080

setup-claude also adds mcp__project-orchestrator__* to the allowed tools of ~/.claude/settings.json, so Claude Code does not ask before every call.

Check that it works

In Claude Code, run /mcp: project-orchestrator should be listed. Then ask for the list of projects: Claude calls project(action: "list").

Claude Code

# in Claude Code/mcp# then ask: "List all registered projects"# Claude calls: project(action: "list")

Any MCP client, stdio

mcp_server is a thin proxy: it speaks MCP on stdio and forwards each call to the REST API. It never connects to Neo4j itself. Set PO_AUTH_TOKEN, or PO_JWT_SECRET to let it generate a token at startup.

~/.claude/mcp.json

{  "mcpServers": {    "project-orchestrator": {      "command": "/path/to/mcp_server",      "env": {        "PO_SERVER_URL": "http://127.0.0.1:8080",        "PO_AUTH_TOKEN": "<jwt-session-token>"      }    }  }}

Try: switch between stdio, Claude Code and a raw HTTP request, then copy the block

MCP tools

31 tools, one call shape

Every tool takes an action parameter and dispatches to one operation. Search by tool, action or parameter, then copy the exact call.

33 tools

plan

Plans with dependency graph, waves, critical path, and the autonomous runner.

Planning and delivery 27 actions

Example call

plan(  action: "create",  title: "Migrate session store to Redis",  priority: 8)

Actions

+21 more
All examples (4)

Parameters

plan_idproject_idtitledescriptionpriorityconstraintsstatussearchlimitoffsetsort_bysort_orderpriority_minpriority_maxcwdproject_slugtrigger_idtrigger_typeconfigcooldown_secsrun_idrun_idstask_idparent_session_idcustom_sectionsprovidermodeltask_class

Try: search a tool, use the arrow keys in the list, open the examples and copy any call

Argument values such as <uuid> are placeholders. The action and parameter names are read from the server source.

Architecture

One Rust server, three stores, any client

Clients never touch the databases. They talk to the server, which parses code, serves the API and streams events.

Select a component to see its role and the flows that reach it, or follow a tool request through the system.

Try: hover or select a component, or follow a request step by step

How they talk

  • MCP clients / mcp_serverstdio
  • MCP clients / orchestratorHTTP /mcp
  • mcp_server / orchestratorREST
  • Desktop app / orchestratorREST + WebSocket
  • WebSocket clients / orchestratorWebSocket
  • orchestrator / Neo4jbolt
  • orchestrator / MeilisearchHTTP
  • orchestrator / NATSNATS
  • orchestrator / ClaudeSDK

Code parsing

17 languages, parsed with tree-sitter

Each file is parsed into functions, structs, traits, enums, imports, impl blocks and call edges, then stored in the graph.

17 languages

Hover, focus or tap a language to see the kind of symbols PO extracts from it.

Try: hover or tap a language

Per file: functions, structs, traits, enums, imports, impl blocks, function calls with a confidence score.

JavaScript files (.js, .jsx, .mjs, .cjs) are read with the TypeScript grammar.

API and events

REST for state, WebSockets for change

Plans, code, notes and the rest are plain JSON over HTTP. Changes are pushed on WebSockets.

Main REST endpoints

Most routes sit behind the auth middleware. When no auth section is configured, the API is open.

GET/healthLiveness
GET/api/versionServer version
GET/api/projectsList projects (POST creates)
POST/api/projects/{slug}/syncParse a project into the graph
GET/api/plans/{plan_id}/wavesParallel waves of a plan
POST/api/plans/{plan_id}/runStart the runner on a plan
GET/api/code/searchSearch code
GET/api/code/impactImpact analysis
GET/api/notes/searchSearch notes
GET/api/decisions/searchSearch decisions
POST/api/reasonReasoning over the graph
POST/mcpMCP over Streamable HTTP

WebSocket streams

  • /ws/events

    Every create, update, delete, link, unlink and status change, as one JSON event. Filter with the entity_types, project_id and layers query parameters.

  • /ws/chat/{session_id}

    Conversation with the assistant. Send user_message, interrupt, permission_response, input_response, set_permission_mode and set_model (the model changes live, or at the next resume if the session is idle); receive the chat events, replayed from last_event after a reconnect.

  • /ws/run/{run_id}

    One stream for a plan run: runner events (task started, wave started...) plus the chat events of every child session.

Browsers authenticate with a cookie, or with a one-time ticket from POST /auth/ws-ticket passed as the ticket parameter.

Live event stream, sample

The shape is the real one (CrudEvent on /ws/events). The events themselves are made up for this illustration.

10 events shown, 10 received

A /ws/events message

/ws/events

{  "entity_type": "task",  "action": "status_changed",  "entity_id": "<uuid>",  "payload": { "old_status": "pending", "new_status": "in_progress" },  "timestamp": "2026-10-05T10:00:00Z",  "project_id": "<uuid>"}

Try: filter by type, pause the stream, select an event to see its message

Extend

Three ways to make PO yours

All three are available through the same MCP tools.

  • Protocols

    Define a finite state machine with states and transitions, start a run, and let agents move it forward with the protocol tool.

  • Skills

    Skills are clusters of notes and code that emerge from use; the skill tool activates, exports and imports them across projects and instances.

  • MCP federation

    mcp_federation connects external MCP servers over stdio, sse or streamable_http, so their tools are reachable through PO.

Contribute

Got an idea, or hit a bug? Tell us.

Project Orchestrator is open source. Ideas and bug reports are both opened as issues on GitHub, where anyone can read them.

Request a feature

Describe the problem you want solved, and what you do today to work around it. A clear problem is easier to discuss than a finished solution.

It opens as a public issue on GitHub, where the maintainers and other users can read it and add to it.

Report a bug

Tell us what you did, what you expected and what happened instead. The more exact the steps, the easier it is to reproduce the problem.

It opens as a public issue on GitHub, where the maintainers and other users can read it and add to it.

A good report includes

  • The version of Project Orchestrator you run, for example the tag of a release on the Releases page.
  • Your operating system and its version.
  • The steps that lead to the problem, in order, and what you expected instead.
  • The exact error message or a screenshot, if there is one.