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, dashboard
trigger	Trigger new runs
repo:write	Cancel runs, rerun, reorder queue, upload/delete pipeline files, manage projects and agents
pipeline:write	Manage pipelines, trigger configs, create projects
token:admin	Create and delete trigger tokens

Astuce

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

Configuration

Claude Code

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

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

Cursor

.cursor/mcp.json

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

~/.cursor/mcp.json

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

GitHub Copilot

.vscode/mcp.json

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

settings.json

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

OpenCode

opencode.json

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

~/.config/opencode/opencode.json

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

Windsurf

~/.codeium/windsurf/mcp_config.json

{
  "mcpServers": {
    "actionforge-orch": {
      "url": "https://orch.actionforge.dev/api/v2/mcp",
      "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_by_number	Get a run by its human-readable run number (e.g. #7) instead of hex ID
list_attempts	List all attempts (re-runs) for a given run number
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
get_dashboard	Get a dashboard overview: projects with latest run status, recent runs, and agent statuses
list_agents	List registered agents with status, labels, and last heartbeat
list_agent_instances	List runner instances (processes) registered under an agent pool
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
browse_tree	Browse the directory tree of an orchestrator-managed project
get_file_content	Get the content of any file in an orchestrator-managed project
list_trigger_configs	List trigger configurations with versions and matrix definitions
list_trigger_tokens	List trigger tokens for a project (token values are not returned)
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
update_project	repo:write	Update project settings: visibility, VCS type, URL, or default ref
delete_project	repo:write	Delete a project and all its data (irreversible)
update_agent_labels	repo:write	Update the labels on an agent
delete_agent	repo:write	Delete (unregister) an agent
restart_agent_instance	repo:write	Restart a runner instance by removing its registration
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
delete_trigger_config	pipeline:write	Delete a trigger config and all its versions
create_trigger_token	token:admin	Create a trigger token for a project (label is applied as required label on jobs)
delete_trigger_token	token:admin	Delete (revoke) a trigger token

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. list_agent_instances to see individual runner processes
3. get_agent_metrics for CPU/memory details
4. get_queue to see pending work
5. cancel_runs to clear stuck runs

Manage agents and labels

1. list_agents to see current labels
2. update_agent_labels to change which jobs an agent can claim
3. restart_agent_instance to kick a stuck runner process
4. delete_agent to unregister an agent entirely

Quick overview

1. get_dashboard for a snapshot of all projects, recent runs, and agent statuses
2. get_run_by_number to look up a specific run (e.g. “what happened in run #7?”)