Orchestrator MCP

🔧 Orchestrator MCP

The Orchestrator MCP server gives AI agents full CI/CD control — trigger runs, monitor agents, manage pipelines, inspect logs, and control the job queue. All operations require authentication.

Authentication

Every request must include an Authorization header with a valid Personal Access Token (PAT). Create one at 🔑 Settings → Personal Access Tokens.

PAT tokens have scopes that control access:

Scope	Permissions
read	List and view projects, runs, agents, queue, artifacts, pipelines
trigger	Trigger new runs
repo:write	Cancel runs, rerun, reorder queue, upload/delete pipeline files
pipeline:write	Manage pipelines, trigger configs, create projects
secret:write	List secret keys (values are never exposed)

Tipp

Session-based authentication (browser cookie) also works and grants all scopes.

Configuration

Claude Code

claude mcp add --transport http actionforge-orch \
  --header "Authorization: Bearer YOUR_PAT_TOKEN" \
  https://app.actionforge.dev/api/v2/mcp/orch

Cursor

Add to .cursor/mcp.json in your project:

{
  "mcpServers": {
    "actionforge-orch": {
      "url": "https://app.actionforge.dev/api/v2/mcp/orch",
      "headers": {
        "Authorization": "Bearer YOUR_PAT_TOKEN"
      }
    }
  }
}

GitHub Copilot

Add to .vscode/mcp.json in your project:

{
  "servers": {
    "actionforge-orch": {
      "type": "http",
      "url": "https://app.actionforge.dev/api/v2/mcp/orch",
      "headers": {
        "Authorization": "Bearer YOUR_PAT_TOKEN"
      }
    }
  }
}

OpenCode

Add to opencode.json in your project:

{
  "mcp": {
    "actionforge-orch": {
      "type": "remote",
      "url": "https://app.actionforge.dev/api/v2/mcp/orch",
      "headers": {
        "Authorization": "Bearer YOUR_PAT_TOKEN"
      }
    }
  }
}

Windsurf

Add to your ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "actionforge-orch": {
      "url": "https://app.actionforge.dev/api/v2/mcp/orch",
      "headers": {
        "Authorization": "Bearer YOUR_PAT_TOKEN"
      }
    }
  }
}

Available Tools

Read Tools (scope: read)

Tool	Description
list_projects	List CI/CD projects accessible to the authenticated user
get_project	Get detailed info about a specific project
list_runs	List runs with filters by project, status, and pipeline
get_run	Get detailed run info including status, timing, jobs, trigger metadata
get_run_logs	Get log output for a run or specific job (supports pagination)
list_jobs	List all jobs for a specific run with matrix values and status
list_agents	List registered agents with status, labels, and last heartbeat
get_agent_metrics	Get CPU, memory, and network metrics for an agent
get_queue	Get the current job queue in priority order
list_artifacts	List build artifacts, optionally filtered by run ID
list_pipelines	List pipeline scripts across projects
get_pipeline_content	Get contents of a specific pipeline script
list_trigger_configs	List trigger configurations with versions and matrix definitions
list_organizations	List organizations the user belongs to
list_commits	List recent git commits for orchestrator-managed projects
get_commit_diff	Get the diff for a specific commit

Write Tools

Tool	Scope	Description
trigger_run	trigger	Trigger a new CI/CD run for a project
trigger_run_by_config	trigger	Trigger a run using a named trigger config with matrix subsetting
cancel_runs	repo:write	Cancel one or more pending/running runs
rerun	repo:write	Re-run a completed run with same configuration
reorder_queue	repo:write	Reorder the job queue by priority
upload_pipeline_file	repo:write	Create or update a pipeline script in an orchestrator-managed project
delete_pipeline_file	repo:write	Delete a pipeline script file
create_project	pipeline:write	Create a new CI/CD project
create_trigger_config	pipeline:write	Create a named trigger configuration
create_trigger_config_version	pipeline:write	Add an immutable version to a trigger config
toggle_trigger_config_version	pipeline:write	Enable or disable a trigger config version

Typical Workflows

Trigger and monitor a run

1. list_projects to find the project
2. trigger_run to start a new run
3. get_run to check status
4. get_run_logs to see output

Investigate failures

1. list_runs with status filter to find failed runs
2. get_run_logs to read the failure output
3. list_artifacts to check build artifacts
4. rerun to retry after fixing the issue

Monitor infrastructure

1. list_agents to check agent health
2. get_agent_metrics for CPU/memory details
3. get_queue to see pending work
4. cancel_runs to clear stuck runs