MCP Server

MCP Server

The Colony MCP server (@colony/mcp) exposes Colony pipeline tools inside any MCP-compatible editor — file issues, check pipeline status, estimate costs, trigger retries, and inspect diagnostics without leaving your editor.

It connects directly to Colony’s Postgres pipeline store and the GitHub API. It runs in two modes:

• Local stdio — launched by your editor as a child process on your machine.
• Central HTTP — one shared container on the Colony VM, accessible to all pilot users over Streamable HTTP.

---

Run Modes

Local stdio (colony mcp)

After installing Colony’s CLI, run:

colony mcp

The command reads DATABASE_URL and GITHUB_TOKEN from your environment (or Colony config) and starts the MCP stdio server. Configure your editor to run this command as the MCP server process — the editor manages the process lifetime.

Alternatively, use npx without installing the CLI:

npx @colony/mcp

This fetches and runs the MCP server directly; set the required env vars in the editor config.

Central HTTP (Docker Compose mcp profile)

For shared pilot deployments, start one MCP container on the Colony VM:

docker compose --profile mcp up -d mcp

Before starting, set MCP_AUTH_TOKEN in .env:

MCP_AUTH_TOKEN=$(openssl rand -hex 32)

Pilot users point their MCP clients at:

http://<vm-host>:9300/mcp

with an Authorization: Bearer <MCP_AUTH_TOKEN> header. Expose this endpoint only on a trusted network, VPN, or behind a TLS reverse proxy — the MCP tools can create issues and mutate pipeline state.

---

Editor Configuration

Claude Code

Add to ~/.claude/settings.json (global) or .mcp.json (per-project):

Using colony mcp (installed CLI):

{
  "mcpServers": {
    "colony": {
      "command": "colony",
      "args": ["mcp"],
      "env": {
        "DATABASE_URL": "postgresql://user:pass@host/db",
        "GITHUB_TOKEN": "ghp_..."
      }
    }
  }
}

Using npx @colony/mcp (no install required):

{
  "mcpServers": {
    "colony": {
      "command": "npx",
      "args": ["@colony/mcp"],
      "env": {
        "DATABASE_URL": "postgresql://user:pass@host/db",
        "GITHUB_TOKEN": "ghp_..."
      }
    }
  }
}

Cursor

Add to .cursor/mcp.json (per-project) or ~/.cursor/mcp.json (global):

Using colony mcp (installed CLI):

{
  "mcpServers": {
    "colony": {
      "command": "colony",
      "args": ["mcp"],
      "env": {
        "DATABASE_URL": "postgresql://user:pass@host/db",
        "GITHUB_TOKEN": "ghp_..."
      }
    }
  }
}

Using npx @colony/mcp (no install required):

{
  "mcpServers": {
    "colony": {
      "command": "npx",
      "args": ["@colony/mcp"],
      "env": {
        "DATABASE_URL": "postgresql://user:pass@host/db",
        "GITHUB_TOKEN": "ghp_..."
      }
    }
  }
}

---

Environment Variables

Variable	Required	Description
DATABASE_URL	Yes	Postgres connection string for Colony’s pipeline store
GITHUB_TOKEN	PAT auth only	GitHub personal access token. Not needed when config uses GitHub App auth
MCP_TRANSPORT	No	stdio or http. Defaults to stdio
MCP_AUTH_TOKEN	HTTP mode only	Bearer token required by the HTTP MCP endpoint
MCP_HOST	No	HTTP bind host. Defaults to 0.0.0.0
MCP_PORT	No	HTTP port. Defaults to 9300
MCP_PATH	No	HTTP MCP path. Defaults to /mcp
MCP_CONFIG_PATH	No	Explicit path to colony.config.yaml when not using the default search path
MCP_LOG_LEVEL	No	Log level (debug, info, warn, error). Defaults to info

---

Tool Reference

All 9 tools are listed below. Arguments marked required must be provided; all others are optional. The repo argument always takes owner/name format (e.g. RunColony/colony).

colony_work

Query work items and pipeline state. The view parameter selects the operation.

Argument	Required	Type	Description
view	Yes	string	status: pipeline health and queue depth; list: browse issues with filters; diagnose: investigate a specific issue; findings: agent-recorded findings
repo	Required for diagnose, findings	string	Repository in owner/name format. Optional for status and list (omit for a cross-repo aggregate).
issue_number	Required for diagnose	number	Issue number — required for diagnose; optional filter for findings
tenant_id	No	string	Tenant external ID for ambiguous repo names — findings view only
state	No	string	Filter by issue state — list view only
label	No	string	Filter by label — list view only
since	No	string	Start date filter (ISO 8601) — list view only
until	No	string	End date filter (ISO 8601) — list view only
limit	No	number	Maximum items to return — list (default 50, max 200) or findings (default 100, max 200)
offset	No	number	Items to skip for pagination (default 0) — list view only
pr_number	No	number	Pull request number filter — findings view only
status	No	string	Filter by finding status (e.g. open, resolved) — findings view only
category	No	string	Filter by finding category — findings view only
severity	No	string	Filter by finding severity — findings view only

View descriptions:

• status — pipeline health: worker availability, queue depth by task type, active issue count by state, and total cost for the current period. repo optional; omit for a cross-repo aggregate.
• list — list issues filtered by state, with cost, cycle time, and assignees. repo optional for cross-repo queries.
• diagnose — diagnose why an issue is in its current state: state history, block reason, execution telemetry, and actionable recommendations. Requires repo and issue_number.
• findings — list agent findings for a repo or issue: observations, risks, and review findings. Requires repo.

---

colony_file_issue

File and enqueue an issue with Colony-aware formatting. Reads .colony/conventions.md from the target repo, applies appropriate labels, and validates scope.

Argument	Required	Type	Description
repo	Yes	string	Repository in owner/name format
title	Yes	string	Issue title
body	Yes	string	Issue body in markdown
labels	No	string[]	Additional labels to apply
complexity_hint	No	small | medium | large	Complexity hint for the analyzer

---

colony_estimate

Cost and time estimate before filing. Takes an issue description and repo, returns estimated cost (USD), confidence level, and likely outcome.

Argument	Required	Type	Description
repo	Yes	string	Repository in owner/name format
description	Yes	string	Issue description to estimate
complexity	No	small | medium | large	Optional complexity tier filter for percentile computation

---

colony_review

Get Colony’s review verdict on a PR. Returns the reviewer’s structured analysis: verdict, findings, and confidence.

Argument	Required	Type	Description
repo	Yes	string	Repository in owner/name format
pr_number	Yes	number	Pull request number

---

colony_act

Perform an operator action on a work item. The action parameter selects the operation.

Argument	Required	Type	Description
repo	Yes	string	Repository in owner/name format
issue_number	Yes	number	Issue number to act on
action	Yes	string	Action to perform — see table below

Available actions:

Action	Description	Availability
pause	Pause processing; the issue can be resumed later.	Always
resume	Resume a paused issue.	Always
cancel	Cancel the work item and close it.	Always
retry	Re-enqueue the current state’s executor after failure.	Always
reimplement	Discard the current PR and return to analysis.	Workflow-declared
reanalyze	Re-run analysis with new context.	Workflow-declared
reopen	Reopen a completed issue; sends it back to intake.	Workflow-declared

Workflow-declared actions (reimplement, reanalyze, reopen) are only available when the issue’s active workflow declares them. A workflow may rename these actions but not withhold the platform actions (pause, resume, cancel, retry). resume is an action in colony_act — there is no separate resume tool.

---

colony_tracks

List and manage self-improvement tracks for a repo. Shows active tracks, completion counts, and cooldown status.

Argument	Required	Type	Description
repo	Yes	string	Repository in owner/name format

---

colony_import_plan

Publish a pre-decomposed plan as dependency-linked Colony issues. Dependents are created blocked until their prerequisites complete. Idempotency is best-effort by title — do not run two overlapping imports concurrently. Use dry_run to preview classification without creating anything.

Set as_epic to import the plan as an epic: tasks become subtasks of a shared parent issue, all targeting an epic/<n> branch that is reviewed and merged as a unit.

Argument	Required	Type	Description
repo	Yes	string	Repository in owner/name format
tasks	Yes	array	Structured task array — see schema below
dry_run	No	boolean	Preview classification without creating issues
as_epic	No	boolean	Import as an epic with a shared parent issue and epic/<n> branch
epic_title	No	string	Title for the epic parent issue (used only when as_epic is true)
epic_body	No	string	Body for the epic parent issue (used only when as_epic is true)

tasks array item schema:

Field	Required	Type	Description
key	Yes	string	Short unique identifier, no spaces (e.g. auth-api, migrate-db)
title	Yes	string	Concise action phrase ≤ 72 chars, starts with a verb
body	No	string	Markdown issue body — background, acceptance criteria, constraints
dependsOn	No	string[]	Array of key values this task depends on (omit or [] for root tasks)
needsHuman	No	boolean	true if the task requires human intervention before Colony can proceed
crossRepo	No	string	"owner/other-repo" if the task belongs to a different repository

---

colony_intelligence

List v2 repo intelligence items (mode: list, default), or run retrieval debug for a specific agent role (mode: retrieve). List mode returns architecture facts, invariants, failure patterns, design decisions, and other evidence-backed intelligence. Retrieve mode runs the same ranked-snippet retrieval an agent would receive and returns snippets, candidate files, and token estimates.

Argument	Required	Type	Description
repo	Yes	string	Repository in owner/name format
mode	No	string	list (default): filtered intelligence items; retrieve: retrieval debug for the given agent role
tenant_id	No	string	Tenant external ID for ambiguous repo names
kind	No	string	Filter by kind (e.g. architecture, invariant, failure_pattern, design_decision) — list mode
status	No	string	Filter by status: candidate, observed, proposed, approved, dismissed, superseded — list mode
scope_kind	No	string	Filter by scope kind (e.g. repo, package, path, file, symbol) — list mode
scope_ref	No	string	Filter by scope reference value — list mode
tag	No	string	Filter by tag — list mode
source	No	string	Filter by source agent or system — list mode
min_confidence	No	number	Minimum confidence threshold (0–1) — list mode
limit	No	number	Maximum results (default 100, max 500) — list mode
agent	Required for retrieve mode	string	Agent role: analyzer, planner, developer, reviewer, retrospector — retrieve mode
issue	No	number	Issue number to scope retrieval — retrieve mode
pr	No	number	Pull request number to scope retrieval — retrieve mode
budget	No	number	Token budget for rendered markdown — retrieve mode

---

colony_workflows

List workflow definitions registered for the tenant associated with the given repo, or return the full parsed definition for a specific workflow when workflow_id is given. Defaults to the latest version when version is omitted.

Argument	Required	Type	Description
repo	Yes	string	Repository in owner/name format
workflow_id	No	string	Workflow identifier to fetch (e.g. colony-default); when omitted, lists all definitions
version	No	number	Workflow version number (defaults to latest; only used when workflow_id is given)
tenant_id	No	string	Tenant external ID for ambiguous repo names

---

Slash Command Pack

Claude Code slash commands that wrap the MCP tools in structured conversational prompts. The files live in .claude/commands/colony/ and are picked up automatically by Claude Code when the project is open. Copy them to ~/.claude/commands/colony/ for global availability.

Command	Invocation	What it does	MCP tools used
brainstorm	/colony:brainstorm [repo]	Interview → estimate → file a Colony issue	colony_estimate, colony_file_issue
plan	/colony:plan [repo]	Decompose work into dependency-linked tasks and import as a plan	colony_import_plan (dry-run preview + live import)
report	/colony:report [repo] [time-window]	Summary report: workers, queue, active issues, cost, findings	colony_work (views: status, list, findings)
issue-status	/colony:issue-status <repo> <issue>	Diagnose a specific issue: state history, block reason, recommendations	colony_work (views: diagnose, status)

Usage examples:

/colony:brainstorm RunColony/colony
/colony:plan acme/webapp
/colony:report acme/webapp 30d
/colony:issue-status acme/webapp 42
/colony:issue-status acme/webapp#42

Editor-side vs. GitHub-comment commands: These slash commands operate via the MCP server from your editor. They are distinct from GitHub-comment slash commands (/colony:retry, /colony:decompose, /colony:cancel, etc.) that control the pipeline from issue comments on GitHub.