Documentation

Learn how to set up and use Orchestra MCP.

Getting Started

1. Register an Account

Create your Orchestra MCP account at orchestra-mcp.com/register. You can sign up with email or GitHub OAuth.

After registration, you will be guided through onboarding to set up your organization and invite team members.

2. Get Your MCP Token

Navigate to Dashboard → Tokens and create a new MCP token. Copy the token -- it will only be shown once.

orch_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxx

3. Connect Claude Code

Add Orchestra MCP to your Claude Code configuration. Create or update .mcp.json in your project root:

{
  "mcpServers": {
    "orchestra": {
      "type": "sse",
      "url": "https://your-instance.orchestra-mcp.com/mcp/sse",
      "headers": {
        "Authorization": "Bearer orch_live_xxxx..."
      }
    }
  }
}

Restart Claude Code and you should see 55 MCP tools available.

MCP Tools Reference

Orchestra MCP provides 55 tools across 11 categories. All tools follow the MCP protocol and are accessible through any MCP-compatible client.

Agents

create_agent

Create a new AI agent with role, skills, and memory scope

list_agents

List all agents in the current project or organization

get_agent

Get details of a specific agent including memory and activity

update_agent

Update agent configuration, role, or skills

delete_agent

Remove an agent and optionally archive its memory

Tasks

create_task

Create a task with title, description, assignee, and priority

list_tasks

List tasks with filters for status, assignee, and project

update_task

Update task status, assignee, priority, or description

complete_task

Mark a task as complete with optional completion notes

delete_task

Delete a task (soft delete with audit trail)

Projects

create_project

Create a new project with name, description, and settings

list_projects

List all accessible projects in the organization

get_project

Get full project details including stats and recent activity

update_project

Update project settings, name, or description

archive_project

Archive a project (preserves all data, hides from active list)

Memory

store_memory

Store a memory entry with content, tags, and vector embedding

search_memory

Semantic search across memory entries using vector similarity

list_memories

List memory entries with tag and date filters

delete_memory

Delete a specific memory entry

clear_memory

Clear all memory for a specific scope (agent, project, or session)

Activity

log_activity

Log an activity event with type, description, and metadata

list_activities

List activity feed with filters for type, agent, and project

get_activity

Get details of a specific activity entry

Decisions

log_decision

Log an architectural decision with rationale and alternatives

list_decisions

List all decisions for a project or organization

get_decision

Get full decision details including discussion and outcome

Sessions

create_session

Start a new session with context and goals

resume_session

Resume an existing session with full context restoration

end_session

End a session and persist final state to memory

list_sessions

List sessions for the current user or agent

Notes

create_note

Create a note with markdown content, tags, and links

list_notes

List notes with tag, search, and date filters

update_note

Update note content, tags, or links

delete_note

Delete a note (soft delete)

Skills & Workflows

create_feature

Create a feature workflow with gates and review checkpoints

advance_feature

Advance a feature through its workflow gates

submit_review

Submit a code review for a feature at a gate

list_features

List all features with status and gate progress

Specs

create_spec

Create a technical specification with versioning

list_specs

List all specs for a project

update_spec

Update a spec (creates a new version)

GitHub

connect_repo

Connect a GitHub repository to the project

create_pr

Create a pull request with description and reviewers

generate_claude_md

Generate a CLAUDE.md file for the connected repository

list_repos

List connected GitHub repositories

sync_repo

Sync repository metadata and branch information

Self-Hosting

Docker Setup

Orchestra MCP can be self-hosted using Docker Compose. Clone the repository and start the services:

git clone https://github.com/orchestra-mcp/framework.git
cd framework
cp .env.example .env

# Start all services (PostgreSQL, GoTrue, MCP server)
docker compose up -d

# Run database migrations
docker compose exec app php artisan migrate --seed

Migrations

Database migrations create all required tables for organizations, users, tokens, agents, tasks, memory, and more:

php artisan migrate        # Apply all migrations
php artisan migrate:status # Check migration status
php artisan db:seed        # Seed default data

Configuration

Key environment variables for self-hosted deployments:

APP_URL Base URL of your Orchestra MCP instance

DB_CONNECTION Database driver (pgsql recommended)

SUPABASE_URL Your Supabase instance URL for auth and realtime

SUPABASE_KEY Supabase service role key

GITHUB_CLIENT_ID GitHub OAuth app client ID (for login and repo access)

STRIPE_KEY Stripe publishable key (for billing, optional)

API Reference

MCP Protocol

Orchestra MCP implements the Model Context Protocol (MCP) specification. Clients connect via Server-Sent Events (SSE) for real-time bidirectional communication.

SSE Endpoint

Connect to the MCP SSE endpoint to establish a persistent connection:

GET /mcp/sse
Authorization: Bearer orch_live_xxxx...
Accept: text/event-stream

The SSE endpoint returns a stream of events including tool results, notifications, and status updates.

Token Authentication

All API requests require a valid MCP token in the Authorization header. Tokens are scoped to a user and organization.

# Create a token via the dashboard, then use it:
curl -H "Authorization: Bearer orch_live_xxxx..." \
     https://your-instance.orchestra-mcp.com/mcp/sse

Token prefixes: Live tokens use orch_live_ and test tokens use orch_test_. Tokens can be revoked at any time from the dashboard.