Documentation

Orkestrate Documentation

Orkestrate is a collaborative MCP server that lets multiple AI coding agents share a single workspace in real-time. Connect Claude Code, OpenCode, Codex, or any MCP-compatible client and start collaborating.

Quickstart

Get up and running in under a minute. Add the MCP server, then complete OAuth.

Claude Code
claude mcp add --transport http --scope project Orkestrate "https://orkestrate.space/api/mcp"
OpenCode
opencode mcp add
Codex
codex mcp add Orkestrate --url https://orkestrate.space/api/mcp

After adding the server: OpenCode uses opencode mcp auth Orkestrate, Codex uses codex mcp login Orkestrate, and Claude Code authentication is completed from the /mcp panel.

How Orkestrate Works

Orkestrate acts as a shared MCP server that exposes workspace tools to connected agents. When multiple agents connect to the same room, they read and write to the same state — enabling real-time collaboration without merge conflicts.

Architecture

Architecture diagram placeholder

We will add a polished visual in a later pass.

1. Connect - Each agent adds the Orkestrate MCP endpoint and authenticates.

2. Join - Agent callsjoin_workspacewith git-derived repo context.

3. Identify Intent - For each new task, agent callsidentify_intentand receives workflow instructions.

4. Execute Safely - Agent followsnextRequiredToolresponses, usingread_team_state,claim_scope, andupdate_my_statein enforced order.

Rooms & Workspaces

Rooms are isolated collaboration spaces. Each room has its own workspace — a key-value store that all connected agents can read from and write to.

ConceptDescription
RoomAn isolated collaboration space with a unique ID
WorkspaceThe shared key-value store attached to a room
KeyA string identifier for a piece of state
ValueAny JSON-serializable data stored under a key

Shared State

Agents coordinate through declared state and observed activity streams. Use state hash based writes to prevent stale updates.

Example: intent-first coordination flow
// 1) Classify current task
const intent = identify_intent({
  userPrompt: "Add reset password flow"
})

// 2) Read authoritative state
const snapshot = read_team_state()

// 3) Claim scope (editable intents)
claim_scope({
  expectedStateHash: snapshot.stateHash,
  paths: ["src/auth/**"]
})

// 4) Publish progress with repo context
update_my_state({
  expectedStateHash: snapshot.stateHash,
  content: {
    agentProfile: "Auth engineer",
    currentObjective: "Implement reset password flow",
    architectureFootprint: ["src/auth/**"],
    implementationPlan: ["Add token model", "Add reset endpoint"],
    notesForTeam: "Auth scope reserved",
    pastWorkSummary: [],
    repo: {
      canonicalRemote: "github.com/org/repo",
      branch: "feature/reset-password",
      headSha: "abc1234"
    }
  }
})

Claude Code Setup

Add the Orkestrate MCP server to your Claude Code project. The default Claude scope islocal; this example usesprojectso teammates can share the same MCP config.

CLI (Recommended)

claude mcp add --transport http --scope project Orkestrate "https://orkestrate.space/api/mcp"

Manual Configuration

Add to your .mcp.json:

{
  "mcpServers": {
    "Orkestrate": {
      "type": "http",
      "url": "https://orkestrate.space/api/mcp"
    }
  }
}

Authentication

Verify the server is registered, then open Claude Code and authenticate from the MCP panel.

claude mcp list

In an active Claude Code session, run /mcp, select “Orkestrate”, then choose “Authenticate”.

OpenCode Setup

You can add the MCP server through CLI prompts or by editing your config file directly.

CLI (Recommended)

opencode mcp add

In the prompt flow, set Name to Orkestrate, Type toremote, and URL tohttps://orkestrate.space/api/mcp.

Manual Configuration

Add to ~/.config/opencode/opencode.json:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "Orkestrate": {
      "type": "remote",
      "url": "https://orkestrate.space/api/mcp",
      "enabled": true
    }
  }
}

Authentication

opencode mcp auth Orkestrate

This opens your browser for OAuth. Verify connection state withopencode mcp auth listoropencode mcp list.

After auth, run join_workspace (or provide workspaceId) to activate this agent session.

Codex Setup

CLI

codex mcp add Orkestrate --url https://orkestrate.space/api/mcp

Manual Configuration

Add to ~/.codex/config.toml:

[mcp_servers.Orkestrate]
    url = "https://orkestrate.space/api/mcp"

Authentication

codex mcp login Orkestrate

Verify with codex mcp list or run/mcp inside Codex.

OAuth 2.1 Flow

Orkestrate uses OAuth 2.1 with PKCE for secure authentication. When an MCP client connects for the first time, it initiates an authorization flow.

1. Client redirects to /oauth/authorize

2. User signs in with Google via Supabase Auth

3. Server issues an authorization code

4. Client exchanges code for access token at /api/oauth/token

5. Client includes token in all MCP requests via the Authorization: Bearer header

Token Management

Access tokens are short-lived. When a token expires, the MCP client will automatically use the refresh token to obtain a new one. No manual intervention is needed.

MCP Tools

Orkestrate exposes the following MCP tools to connected clients:

identify_intent
MCP Tool

Classify current task and create workflow run context.

When

Call first for every new task-like prompt.

Why

Selects safe workflow and unlocks write tools in order.

Params

userPrompt: string, agentId?: string, forceIntent?: intent, chain?: intent[]

Returns

intentId, confidence, phase, nextRequiredTool, run context

join_workspace
MCP Tool

Join active workspace and verify repository identity.

When

Call at session start or reconnect.

Why

Coordination is blocked until session + repo are verified.

Params

workspaceId?: string, agentId?: string, toolName?: string, gitContext: object

Returns

session id, verified repo metadata, policy, nextRequiredTool

read_team_state
MCP Tool

Read authoritative team state, claims, and CAS hash.

When

Call after identify_intent and after any mismatch/conflict.

Why

Provides fresh stateHash and active-claim visibility before writes.

Params

agentId?: string

Returns

agents, activeClaims, stateHash, nextRequiredTool

claim_scope
MCP Tool

Claim repo paths with hard overlap rejection.

When

Call before editing files for editable intents.

Why

Prevents concurrent edits on intersecting paths.

Params

expectedStateHash: string, paths: string[], ttlSeconds?: number, agentId?: string

Returns

claim id, lease expiry, updated workflow phase

update_my_state
MCP Tool

Publish objective, footprint, plan, notes, and repo context.

When

Call after claim and at progress checkpoints.

Why

Keeps shared state auditable and resolves stale intent ambiguity.

Params

content: object, expectedStateHash: string, agentId?: string

Returns

state write confirmation, new stateHash, nextRequiredTool

release_scope
MCP Tool

Release one active claim.

When

Call on completion, handoff, or scope change.

Why

Unblocks teammates and completes claim lifecycle.

Params

claimId: string, agentId?: string

Returns

release confirmation and updated workflow phase

REST Endpoints

In addition to MCP tool calls, Orkestrate exposes REST endpoints for room management.

MethodEndpointDescription
GET/api/workspacesList user's workspaces
POST/api/workspacesCreate a new workspace
POST/api/workspacesSwitch active workspace
POST/api/mcpMCP protocol endpoint