MCP & Editor Integration

Colony Cloud ships a fully hosted MCP server at https://app.runcolony.com/mcp. Configure once with a URL and token — all 18 Colony tools are available in every editor session. No local installation required.

Note

Self-hosted Colony? If you run Colony yourself, use the @colony/mcp package instead. It connects directly to your local Postgres instance and GitHub token via stdio transport. This guide is for Colony Cloud users at app.runcolony.com.

Tip

Prefer a chat surface inside the dashboard? See the Operator Assistant.

Prerequisites

• An active Colony Cloud account at app.runcolony.com
• A verified email address (required to create API tokens)
• At least one repository enabled in your organization

1. Generate an API Token

1. Sign in and go to Settings → Organization → Integrations.
2. Click New Token.
3. Give the token a name (e.g. claude-code or cursor-work).
4. Click Create — copy the token value (cct_…) immediately; it is shown only once.
5. Optionally set an expiry date for the token.

Tokens are scoped to your organization. Anyone with the token can access your org’s pipeline data — treat it like a password.

2. Configure Your Editor

Colony Cloud supports two authentication paths. Both paths provide identical access — the same tools, scopes, and role-based permissions apply regardless of how you authenticate.

CLI clients — static bearer token: Claude Code, Cursor, Continue, and any client that lets you set custom HTTP headers use a static Authorization: Bearer cct_… header. Generate a token from Settings → Organization → Integrations and paste it into your client config.

GUI clients — OAuth 2.1: Claude Desktop and claude.ai use OAuth 2.1. You do not need to generate a token manually. Enter https://app.runcolony.com/mcp as the server URL — the client handles browser-based authorization and token exchange automatically.

Claude Code

Option A — CLI (recommended)

claude mcp add --transport http colony https://app.runcolony.com/mcp \
  --header "Authorization: Bearer cct_YOUR_TOKEN"

This writes the server entry to your project’s .mcp.json (or ~/.claude/mcp.json if you omit --scope project).

Option B — Manual JSON config

Add to .mcp.json in your project root (or ~/.claude/mcp.json for global use):

{
  "mcpServers": {
    "colony": {
      "type": "http",
      "url": "https://app.runcolony.com/mcp",
      "headers": {
        "Authorization": "Bearer cct_YOUR_TOKEN"
      }
    }
  }
}

Cursor

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

{
  "mcpServers": {
    "colony": {
      "url": "https://app.runcolony.com/mcp",
      "headers": {
        "Authorization": "Bearer cct_YOUR_TOKEN"
      }
    }
  }
}

Claude Desktop

1. Open Claude Desktop and go to Settings → Developer → MCP Servers.
2. Click Add Server and select Remote MCP Server.
3. Enter https://app.runcolony.com/mcp as the server URL.
4. Claude Desktop opens a browser window — sign in to Colony Cloud and approve access.
5. After approving, Claude Desktop stores the OAuth tokens automatically. No token to copy.

claude.ai

1. In claude.ai, open Settings → Integrations.
2. Click Add integration and enter https://app.runcolony.com/mcp as the MCP server URL.
3. A browser consent screen opens — sign in to Colony Cloud and approve the requested scopes.
4. Once approved, Colony tools are available in your claude.ai conversations.

Generic Streamable-HTTP client

The Colony MCP endpoint uses Streamable HTTP transport (the 2025-03-26 MCP spec):

Parameter	Value
Endpoint	https://app.runcolony.com/mcp
Method	POST only — GET returns 405
Auth header	Authorization: Bearer cct_YOUR_TOKEN (CLI/static-token clients)
Content-Type	application/json
Accept	application/json, text/event-stream
Sessions	Stateless — no session ID management required

Example initialize request:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "initialize",
  "params": {
    "protocolVersion": "2025-03-26",
    "capabilities": {},
    "clientInfo": { "name": "my-client", "version": "1.0" }
  }
}

How OAuth 2.1 works

GUI clients like Claude Desktop and claude.ai use a standard OAuth 2.1 authorization code flow with PKCE. Here is what happens under the hood when a client connects for the first time:

1. Discovery — the client fetches GET https://app.runcolony.com/.well-known/oauth-authorization-server (RFC 8414) to learn the authorization, token, and registration endpoint URLs.
2. Dynamic client registration — the client calls POST https://app.runcolony.com/oauth/register (RFC 7591) with its redirect URIs. Colony Cloud issues a client_id (and optionally a client_secret for confidential clients).
3. Authorization + consent — the client redirects the user’s browser to GET https://app.runcolony.com/oauth/authorize with response_type=code, client_id, redirect_uri, the requested scope, and a PKCE code_challenge (S256). The user signs in and approves.
4. Token exchange — after the user approves, the browser is redirected back to the client with an authorization code. The client calls POST https://app.runcolony.com/oauth/token with grant_type=authorization_code, the code, redirect_uri, client_id, and the PKCE code_verifier.
5. Token lifecycle — access tokens (mcp_at_ prefix) expire after 15 minutes. Refresh tokens (mcp_rt_ prefix) expire after 30 days. Compliant clients refresh access tokens silently using grant_type=refresh_token. Refresh token rotation is applied — each refresh issues a new refresh token and revokes the previous one.

Scopes: Colony Cloud supports three scopes: mcp (full access), mcp:read (read-only tools only), and mcp:write (mutating tools only). Most clients request mcp:read by default.

3. Verify the Connection

After configuring your editor, ask your AI assistant to call colony_status:

“What is the current Colony pipeline status for owner/repo?”

The assistant should return active issue counts and monthly cost. If the tool call succeeds, the connection is working.

You can also call tools/list directly to confirm all 18 tools are registered:

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/list",
  "params": {}
}

4. Available Tools

All repo values use owner/name format (e.g. RunColony/colony).

Tool	R/W	Description	Required inputs	Optional inputs
colony_status	Read	Pipeline state: active issue count by state and total cost for the current period	—	repo
colony_issues	Read	List issues with cost, cycle time, and current assignee; supports filtering by repo, state, label, and date range	—	repo, state, label, since (ISO 8601), until (ISO 8601), limit (default 50, max 200), offset
colony_file_issue	Write	File and enqueue an issue with Colony-aware formatting; applies colony:enqueue and optional complexity/epic labels	repo, title, body	labels (array), complexity_hint (small/medium/large)
colony_estimate	Read	Cost and time estimate before filing; returns estimated cost (USD), confidence, and historical examples	repo, description	complexity (small/medium/large)
colony_review	Read	Get Colony’s review verdict on a PR; returns verdict, structured findings, and review cost	repo, pr_number	—
colony_pause	Write	Pause processing of an issue; the issue can be resumed later	repo, issue_number	—
colony_cancel	Write	Cancel processing of an issue; moves it to done state	repo, issue_number	—
colony_retry	Write	Retry a done issue; resets it to new state for re-processing	repo, issue_number	—
colony_resume	Write	Resume a paused issue, restoring it to its pre-pause state and re-enqueuing a work task	repo, issue_number	—
colony_tracks	Read	List self-improvement tracks for a repo; shows completion counts, cooldown status, and active issue	repo	—
colony_why	Read	Diagnose why an issue is in its current state; returns state history, block reason classification, execution telemetry, active tasks, and actionable recommendations	repo, issue_number	—
colony_import_plan	Write	Import a structured task array and create GitHub issues; validates the DAG upfront (cycles, dangling deps), creates issues, then writes pipeline rows with dependency edges; idempotent	repo, tasks (array of task objects: key, title, body, dependsOn, needsHuman, crossRepo)	dry_run
colony_findings	Read	List structured agent findings (observations, risks, review findings) from the pipeline for a repo	repo	issue_number, pr_number, status (open/accepted/resolved/dismissed/superseded), category, severity (info/low/medium/high/critical), finding_type, agent_name, limit (default 100, max 200)
colony_intelligence	Read	List v2 repo intelligence items: architecture facts, invariants, failure patterns, and design decisions	repo	kind, status (candidate/observed/proposed/approved/dismissed/superseded), scope_kind, scope_ref, tag, source, min_confidence (0–1), limit (default 100, max 500)
colony_intelligence_retrieve	Read	Preview the ranked intelligence snippets an agent role would receive for a repo/issue/PR; uses pgvector cosine-distance when embeddings are configured, falls back to quality-score ordering otherwise (approximate preview — full retrieval also applies anchor extraction and code-map recall)	repo, agent (analyzer/planner/developer/reviewer/retrospector)	issue, pr, budget, tenant_id
colony_create_draft	Write	Create a draft issue in Colony Cloud’s Drafts surface for operator refinement before pipeline submission; use instead of colony_file_issue when the issue needs human review first	repo, title, body	issue_type (bug/feature/refactor/spike), source_metadata (object: calling_tool, conversation_summary, session_id)
colony_workflows	Read	List workflow definitions registered for the tenant; returns workflow id, version, source, name, and description	repo	—
colony_workflow_show	Read	Return the parsed YAML and metadata for a specific workflow definition; defaults to the latest version	repo, workflow_id	version

Example: colony_status

Input:

{ "repo": "RunColony/colony" }

Output:

{
  "repos": [
    {
      "repo": "RunColony/colony",
      "activeIssueCount": {
        "analyzing": 1,
        "ready-for-dev": 3,
        "in-review": 1
      },
      "totalCostCurrentMonth": 12.50
    }
  ]
}

Example: colony_why

Input:

{ "repo": "RunColony/colony", "issue_number": 42 }

Output: A multi-line diagnostic report including state history, block reason classification (transient / permanent / unknown), execution telemetry per invocation, active tasks, and numbered recommended actions.

Example: colony_import_plan

Input:

{
  "repo": "RunColony/colony",
  "tasks": [
    {
      "key": "auth-middleware",
      "title": "Refactor auth middleware to use JWT",
      "body": "Replace session cookies with JWT tokens...",
      "dependsOn": []
    },
    {
      "key": "add-tests",
      "title": "Add tests for refactored auth middleware",
      "body": "Write unit and integration tests for the new JWT flow.",
      "dependsOn": ["auth-middleware"]
    }
  ],
  "dry_run": false
}

Output:

{
  "roots": [{ "key": "auth-middleware", "issueNumber": 201, "url": "https://github.com/..." }],
  "blocked": [{ "key": "add-tests", "issueNumber": 202, "url": "https://github.com/..." }],
  "manual_tasks": [],
  "skipped": [],
  "dependencies": [{ "from": 201, "to": 202 }],
  "cycles": [],
  "errors": []
}

Example: colony_pause / colony_cancel / colony_retry / colony_resume

All four control tools take the same input:

{ "repo": "RunColony/colony", "issue_number": 42 }

Success output varies by tool:

colony_pause and colony_cancel — return the state the issue was in before the operation:

{ "ok": true, "previousState": "ready-for-dev" }

colony_retry — additionally returns the state the issue was reset to ("new"):

{ "ok": true, "previousState": "done", "newState": "new" }

colony_resume — returns restoredState (the pre-pause state the issue is restored to), not previousState:

{ "ok": true, "restoredState": "ready-for-dev" }

Error output (wrong state):

{ "isError": true, "content": [{ "type": "text", "text": "Cannot pause issue in state 'done'" }] }

5. Troubleshooting

401 Unauthorized

Your token is missing or incorrect.

• Check that the Authorization header is Bearer cct_YOUR_TOKEN with no extra spaces.
• Confirm the token was copied correctly — it starts with cct_ followed by a UUID.
• If you deleted the token, generate a new one in Settings → Organization → Integrations.

400 / Tenant Not Resolved

Your org is not connected to a VCS provider, or your account is not a member.

Response body: { "code": "ORG_VCS_NOT_CONNECTED" }

• Go to Settings → VCS Connections and confirm your GitHub organization is linked.
• Confirm you are a member of the Colony Cloud org (not just a GitHub org member).

Token Expired

Tokens have an optional expires_at. Once that date passes, requests return 401.

• Generate a replacement token in Settings → Organization → Integrations.
• Update the token value in your editor’s MCP config.

GET /mcp Returns 405

The Colony Cloud MCP server does not support SSE long-lived sessions (the older MCP transport style). Use HTTP transport (POST), not SSE transport (GET + streaming). See Generic Streamable-HTTP client above.

Tool returns “No VCS connection” error

colony_file_issue and colony_review require a GitHub App installation in your org. If you see errors like No GitHub App installation found for org "owner", install the Colony GitHub App from Settings → Repos & access or your org’s onboarding flow.

OAuth: browser consent screen never opened (Claude Desktop / claude.ai)

The client could not reach the metadata endpoint or failed during dynamic registration.

• Confirm the server URL is exactly https://app.runcolony.com/mcp (no trailing slash, no /api prefix).
• Check that your network allows outbound HTTPS to app.runcolony.com.
• Remove the integration entry and re-add it to restart the registration flow.

OAuth: “access_denied” after the consent screen

You clicked Deny on the Colony Cloud consent screen, or the session expired while the consent screen was open.

• Re-initiate the connection from your client to restart the authorization flow.
• Sign in to Colony Cloud in the browser before re-authorizing if your session has lapsed.

OAuth: access token expired mid-session

Access tokens expire after 15 minutes. Compliant clients (Claude Desktop, claude.ai) refresh them automatically using the refresh token — no action needed. If your client does not support token refresh, disconnect and reconnect to obtain a new token pair.