MCP & Editor Integration
Colony Cloud ships a fully hosted MCP server at https://app.runcolony.com/mcp. Configure once with a URL and connection — all 16 Colony tools are available in every editor session. No local installation required.
Prerequisites
Section titled “Prerequisites”- An active Colony Cloud account at app.runcolony.com
- A verified email address (required to authenticate)
- At least one repository enabled in your organization
1. Connections
Section titled “1. Connections”A connection is the credential that authenticates your editor to the Colony Cloud MCP server — an OAuth 2.1 delegation bounded by your grants that refreshes itself, rather than a static value you copy around.
Anyone with an active connection can access your org’s pipeline data within the scope of its grants — treat it like a password.
2. Configure Your Editor
Section titled “2. Configure Your Editor”OAuth 2.1: Claude Desktop, claude.ai and Claude Code use OAuth 2.1. Enter https://app.runcolony.com/mcp as the server URL — the client handles browser-based authorization and token exchange automatically. This is the recommended path today.
Other clients: any client that supports OAuth for remote MCP servers connects the same way. Colony Cloud has no page for minting a token by hand, so a client without OAuth support can’t connect yet.
Claude Code
Section titled “Claude Code”claude mcp add --transport http colony https://app.runcolony.com/mcpThen run /mcp in Claude Code and sign in to Colony Cloud in the browser. Claude Code refreshes the connection for you.
By default this adds the server for you in this project only. Add --scope project to write it to the project’s .mcp.json, or --scope user to use it in all your projects.
Cursor
Section titled “Cursor”Add to .cursor/mcp.json in your project root:
{ "mcpServers": { "colony": { "url": "https://app.runcolony.com/mcp" } }}Claude Desktop
Section titled “Claude Desktop”- Open Claude Desktop and go to Settings → Developer → MCP Servers.
- Click Add Server and select Remote MCP Server.
- Enter
https://app.runcolony.com/mcpas the server URL. - Claude Desktop opens a browser window — sign in to Colony Cloud and approve access.
- After approving, Claude Desktop stores the OAuth tokens automatically. No token to copy.
claude.ai
Section titled “claude.ai”- In claude.ai, open Settings → Integrations.
- Click Add integration and enter
https://app.runcolony.com/mcpas the MCP server URL. - A browser consent screen opens — sign in to Colony Cloud and approve the requested scopes.
- Once approved, Colony tools are available in your claude.ai conversations.
Generic Streamable-HTTP client
Section titled “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 | OAuth 2.1 — the client discovers the metadata and runs the flow (see below) |
| 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
Section titled “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:
- 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. - Dynamic client registration — the client calls
POST https://app.runcolony.com/oauth/register(RFC 7591) with its redirect URIs. Colony Cloud issues aclient_id(and optionally aclient_secretfor confidential clients). - Authorization + consent — the client redirects the user’s browser to
GET https://app.runcolony.com/oauth/authorizewithresponse_type=code,client_id,redirect_uri, the requestedscope, and a PKCEcode_challenge(S256). The user signs in and approves. - 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/tokenwithgrant_type=authorization_code, the code,redirect_uri,client_id, and the PKCEcode_verifier. - 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 usinggrant_type=refresh_token. Refresh token rotation is applied — each refresh issues a new refresh token and revokes the previous one.
Which org is bound: When you belong to more than one org where you can connect, the consent screen shows an Organization picker, preselected to your session org. The connection binds to the org you pick, and your dashboard session does not change. Orgs where you are a report reader are not offered. If you are a report reader in your session org, the picker shows and preselects the first org where you are a member, so you can still connect that org. If you are a report reader in every org, the consent screen says report readers can’t connect apps and Approve is disabled. If you belong to one org where you can connect, or the org list fails to load, the connection binds to your session org. A connection stays bound to that org for its whole life; to bind another org, connect again and pick it.
Where the bound org is shown: The server’s instructions in the initialize result name the org (name and id), so your client can show it. The Connected apps and Your connected apps headers in Cloud name the org too.
Scopes: Colony Cloud supports two scopes. baseline is read across the five jobs, and it is the default when a client requests no scope. work acts on work items, bounded by your own Work write. The mcp, mcp:read and mcp:write scopes are no longer accepted; reconnecting re-consents under the new scopes.
Lifetime: A connection has an absolute lifetime set by org policy (default 90 days, range 7–365). It is counted from first authorization and applies regardless of use. See Manage connections to view or change it.
Manage connections
Section titled “Manage connections”Administrators open Account → Connections (/account/connections) to see and revoke every OAuth connection that MCP and CLI clients hold. Every member sees and revokes their own in You → Sign-in.
Who sees what
Section titled “Who sees what”- Every member sees the apps they authorized themselves under Your connected apps in You → Sign-in (
/you/sign-in), and can revoke only those. The list comes fromGET /api/orgs/{orgId}/connections?mine=true. - Holders of the
org-connection-revoke-anygrant also see every connection in the organization in Account → Connections, with the person each app acts as.
The Connections page
Section titled “The Connections page”The page lists Chat first, then Connected apps, then Settings. Each connected app is a row showing:
- The app’s name, with “name not verified”.
- What it can do: “Reads work” for the
baselinescope, or “Reads and acts on work” onceworkis added. - Who it acts as (org-wide list only).
- When it was last used, such as “Used 12 min ago”, “Used yesterday” or “Not used in 41 days”, and when it ends, such as “ends 5 January”.
- Copy id and Revoke.
Names are not verified
Section titled “Names are not verified”The name is a claim the app made during dynamic registration, and Colony has not verified it. Before you trust a row, check who it acts as and when it was last used. If you contact support about a connection, select Copy id and include it.
Revoke a connection
Section titled “Revoke a connection”Select Revoke on a row to open a confirmation dialog. Once you confirm, the app loses access immediately and must be authorized again to reconnect.
If the connection was already revoked elsewhere, Colony shows an error and refreshes the list.
Connection lifetime
Section titled “Connection lifetime”Connection lifetime is a row under Settings on the Connections page. A connection ends that many days after it was first authorized, however recently it was used.
Holders of the org-connection-policy-update grant can change it. Select Change, enter a whole number of days from 7 to 365 (the default is 90), and select Save, or Cancel to keep the current value.
Members and connections
Section titled “Members and connections”Removing a member revokes their connection tokens in this organization. Signing a member out does not. See Team & Roles.
3. Verify the Connection
Section titled “3. Verify the Connection”After configuring your editor, ask your AI assistant to call colony_work:
“What is the current Colony pipeline status for
owner/repo?”
The assistant should call colony_work with view: "status" and 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 16 Colony tools are registered:
{ "jsonrpc": "2.0", "id": 2, "method": "tools/list", "params": {}}4. Available Tools
Section titled “4. Available Tools”All repo values use owner/name format (e.g. RunColony/colony).
Scopes and grants
Section titled “Scopes and grants”Every tool needs a scope on the connection, and every write also needs a grant held by the person who authorized it.
- Read tools work on a
baselineconnection, which is the default selection at consent. - Write tools need the
work(Work) scope on the connection and the grant listed for the tool. Without Work, the call fails withrequires the Work scope on this connection. - The fix for a read-only connection is to reconnect the MCP connection and grant Work when you approve it. The consent screen lets you grant Work even when the client requested no scope, and the error names this fix. Existing connections are listed at Account → Connections.
- A Work connection never exceeds your own grants: if you lack the grant a tool needs, the call is refused.
Tool reference
Section titled “Tool reference”| Tool | R/W | Scope | Grant | Description | Required inputs | Optional inputs |
|---|---|---|---|---|---|---|
colony_work | Read | Baseline | — | Query work items and pipeline state. view=status for active issue count by state and total cost; view=list to browse issues with filters; view=diagnose to investigate a specific issue (state history, block reason classification, execution telemetry, recommendations); view=findings for agent-recorded findings; view=transcript to read an item’s agent turns and state transitions by cursor (needs repo and issue_number; pass next_cursor back as cursor, or latest to start after the newest rows; detail is summary by default, or full to add tool results and system rows; limit defaults to 50, max 200; wait_seconds long-polls up to 25 seconds). Transcript is read-only and works on a baseline connection; thinking is never returned and secrets are scrubbed | view | repo, state, workflow, trait, since (ISO 8601), until (ISO 8601), limit, offset, issue_number, change_number, status, category, severity, record_kind, check_name, check_outcome, cursor, detail, wait_seconds, tenant_id |
colony_file_issue | Write | Work | vcs-write | File and enqueue an issue with Colony-aware formatting; applies colony:enqueue and optional complexity/epic labels | repo, title, body | as_epic, complexity_hint (small/medium/large), assignees, constraints (array) |
colony_estimate | Read | Baseline | — | Cost and time estimate before filing; returns estimated cost (USD), confidence, and historical examples | repo, description | complexity (small/medium/large) |
colony_review | Read | Baseline | — | Get Colony’s review verdict on a change; returns verdict, structured findings, and review cost | repo, change_number | — |
colony_act | Write | Work | Per action, see colony_act actions | Perform an operator action on a work item. action selects the operation | repo, issue_number, action | Depends on the action |
colony_tracks | Read | Baseline | — | List self-improvement tracks for a repo; shows completion counts, cooldown status, and active issue | repo | — |
colony_import_plan | Write | Work | vcs-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 by title | repo, tasks (array of task objects: key, title, body, dependsOn, needsHuman, crossRepo) | dry_run, as_epic, initial_state, epic_title, epic_body, assignees, constraints |
colony_intelligence | Read | Baseline | — | List v2 repo intelligence items (mode=list, default): architecture facts, invariants, failure patterns, and design decisions. mode=retrieve previews the ranked intelligence snippets an agent role would receive | repo | mode, kind, status (candidate/observed/proposed/approved/dismissed/superseded), scope_kind, scope_ref, tag, source, min_confidence (0–1), limit, agent (analyzer/planner/developer/reviewer/retrospector), issue, pr, budget, tenant_id |
colony_workflows | Read | Baseline | — | List workflow definitions registered for the tenant; returns workflow id, version, source, name, and description. With workflow_id, returns the full YAML text and parsed definition for that workflow instead | repo | workflow_id, version, tenant_id |
colony_flaky_checks | Read | Baseline | — | List the repo’s flakiest deterministic review checks: checks that failed, then passed on rerun. Returns flakes per evaluation, flake rate, last flake time, and whether each check is quarantined | repo | days (1–90, default 14), limit (1–50, default 10) |
colony_strategy | Write | Work | Autonomy | Operate the strategy loop. generate durably requests a run and returns {ok, requested_at}; approve applies a proposed snapshot at once and returns {ok, version, status} (with edits, it records your edited version as a new operator snapshot); reject needs a non-empty reason and returns {ok, version}; revert applies the previous snapshot’s tracks again as a new version; list and get read snapshots. Write actions need confirm: true and an actor, which Cloud binds to the signed-in person. Failures carry a leading code: NOT_FOUND, NOT_PROPOSED, ACTOR_REQUIRED, REASON_REQUIRED, NO_ACTIVE_CHARTER, NO_REVERT_TARGET, INVALID (the edits were refused and nothing was written), STALE, CHARTER_CHANGED, or a violation code such as GRANT_EXCEEDED, OPERATOR_TRACK, UNKNOWN_TRACK, INVALID_CRON, OUT_OF_BOUNDS or INVALID_DIRECTIVE. Violations read CODE at path: message | repo, action (generate/approve/reject/revert/list/get) | version, edits, reason, status, limit, confirm |
Cloud-only tools
Section titled “Cloud-only tools”Five tools exist only in Colony Cloud. They run against your Cloud data rather than the pipeline.
| Tool | R/W | Scope | Grant | Description | Required inputs | Optional inputs |
|---|---|---|---|---|---|---|
colony_create_draft | Write | Work | vcs-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 | kind (string, 1–64 characters, taken from the repo’s workflow; defaults to none), source_metadata (object: calling_tool, conversation_summary, session_id) |
colony_queue | Read | Baseline | — | List proposals awaiting operator action in Colony Cloud’s intake queue (drafts); filter by repo and/or lifecycle stage | — | repo, lifecycle (refining/parking/ready/published), limit, offset |
colony_standards | Read | Baseline | — | Fetch the repo’s subscribed standards set at its latest published version: a stamp (set, version, published-at, resolved-at), the standards, and a markdown document headed by the stamp. Read it ahead of the repo’s .colony/conventions.md, never instead of it. Every repo-scoped tool result carries the current stamp in _meta["colony/standards"]; when it differs from yours, re-fetch. A repo with no subscription gets an explicit “no standards set” result. Each fetch is audited | repo | — |
colony_report | Read | Baseline | — | Return Colony Cloud’s reporting status for the org: its report subscriptions (who is subscribed to which tenant’s day, week or month report) and the most recent report email deliveries | — | — |
colony_repos | Read | Baseline | — | List the organization’s enabled repositories as owner/name with their tenant id, to find the repos to pass to other tools or the tenant_id for an org-wide colony_work status call | — | query |
colony_act actions
Section titled “colony_act actions”colony_act takes repo, issue_number and action, plus the extra inputs each action needs. Its scope is Work for every action. The grant differs: most actions need vcs-write; unblock, skip-planning and state override the pipeline and need the Operations grant.
| Action | Extra inputs | request_id | confirm: true | Grant |
|---|---|---|---|---|
pause | — | No | Yes | vcs-write |
resume | — | No | No | vcs-write |
cancel | — | No | Yes | vcs-write |
retry | size (small/medium/large, optional) | Optional (generated when omitted, and returned) | No | vcs-write |
reimplement | text (optional; adoption instructions on a Dependabot tracking issue) | Required | Yes | vcs-write |
adopt | text (instructions that build on a Dependabot update) | Required | Yes | vcs-write |
followup | text (on a Dependabot tracking issue; omit it on an epic) | Required | No | vcs-write |
reanalyze | — | No | No | vcs-write |
reopen | — | No | No | vcs-write |
release | child_number | No | Yes | vcs-write |
invoke | intent, expected_head_sha (optional) | No | Yes | vcs-write |
answer | text | Required | No | vcs-write |
pick | choice, round_id (optional) | Required | No | vcs-write |
constrain | text | Required | No | vcs-write |
constraints | — (read-only: lists the item’s standing constraints and their ids) | No | No | vcs-write |
unconstrain | constraint_id | Required | No | vcs-write |
feedback | text | Required | No | vcs-write |
review | — | Required | No | vcs-write |
priority | level (high/normal/low) | Required | No | vcs-write |
enqueue | level (high/normal/low, optional) | Optional | No | vcs-write |
skip-planning | — | Required | No | Operations |
decompose | — | Required | Yes | vcs-write |
state | target_state, reason | Required | Yes | Operations |
unblock | — | Required | No | Operations |
request_id is a caller-supplied idempotency key of 1–200 characters, unique per tenant. Repeat a call with the same request_id to fetch the outcome of one that is still pending. Reusing it with different arguments is refused.
The confirm step
Section titled “The confirm step”The actions marked confirm: true above, and the colony_strategy write actions (generate, approve, reject, revert), are held on their first call. list and get are reads and are never held. Nothing changes; the result is a non-error message asking you to repeat the call:
{ "status": "confirmation_required", "action": "cancel", "repo": "RunColony/colony", "issue_number": 42, "message": "Cancel on RunColony/colony closes the work as cancelled. Call colony_act again with confirm: true to proceed."}Repeat the same call with "confirm": true to run it.
Removed inputs are refused
Section titled “Removed inputs are refused”A few inputs were removed from the tools. Colony Cloud refuses them by name before the call is dispatched, so a removed filter is never silently dropped (which would, for example, return an unfiltered list). The error reads `key` was removed; use `replacement` instead.
| Tool | Removed input | Use instead |
|---|---|---|
colony_work | pr_number | change_number |
colony_work | label | workflow or trait |
colony_review | pr_number | change_number |
colony_file_issue | labels | as_epic |
colony_strategy | governed | Nothing: strategy tracks are never governed |
The actor is stamped for you
Section titled “The actor is stamped for you”For every write, Colony Cloud sets actor from the authenticated user: their GitHub login, or their email when they have no VCS identity. A value you pass for actor is ignored. Audit entries and pipeline records therefore show who authorized the connection, not what an agent typed. The value you passed is kept only as claimed_actor in the request log.
Example: colony_work (view=status)
Section titled “Example: colony_work (view=status)”Input:
{ "view": "status", "repo": "RunColony/colony" }Output:
{ "repos": [ { "repo": "RunColony/colony", "activeIssueCount": { "analyzing": 1, "ready-for-dev": 3, "in-review": 1 }, "totalCostCurrentMonth": 12.50 } ]}Example: colony_work (view=diagnose)
Section titled “Example: colony_work (view=diagnose)”Input:
{ "view": "diagnose", "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
Section titled “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: (an epicParent object with issueNumber, url and epicBranch is added when an epic is created; warnings appears when an assignee could not be applied)
{ "roots": [ { "key": "auth-middleware", "title": "Refactor auth middleware to use JWT", "issueNumber": 201, "url": "https://github.com/..." } ], "blocked": [ { "key": "add-tests", "title": "Add tests for refactored auth middleware", "issueNumber": 202, "url": "https://github.com/...", "dependsOn": ["auth-middleware"] } ], "dependencies": [ { "childIssue": 202, "parentIssue": 201, "childKey": "add-tests", "parentKey": "auth-middleware" } ], "manualTasks": [], "cycles": [], "skipped": [], "errors": []}Example: colony_act
Section titled “Example: colony_act”Every action takes the same base input, selecting the operation via action:
{ "repo": "RunColony/colony", "issue_number": 42, "action": "pause", "confirm": true }Success output varies by action:
pause and cancel return the state the issue was in before the operation:
{ "ok": true, "previousState": "ready-for-dev" }resume returns restoredState, the pre-pause state the issue is restored to:
{ "ok": true, "restoredState": "ready-for-dev" }reanalyze, reopen, invoke return the workflow transition:
{ "ok": true, "action": "reanalyze", "from": "in-review", "to": "analyzing" }release returns the release record:
{ "ok": true, "status": "released", "child_number": 43, "released_by": "octocat", "released_at": "2026-10-24T09:00:00.000Z"}answer, pick, constrain, unconstrain, feedback, retry, reimplement, adopt, followup, review, priority, skip-planning, decompose, state, unblock are queued as operator commands. Colony waits about ten seconds for the outcome and returns status: "completed" with the request_id, the action, and the action’s own result fields:
{ "status": "completed", "request_id": "retry:3f2a…", "action": "retry" }If the command has not finished in that time, the result is pending. Call again with the same request_id to get the outcome:
{ "status": "pending", "request_id": "fb-42-1", "message": "The command has not finished; call again with the same request_id to get its outcome."}A refusal or failure comes back as an error result, such as Refused: … or Failed: ….
Error output (wrong state):
{ "isError": true, "content": [{ "type": "text", "text": "Cannot pause issue in state 'done'" }] }5. Troubleshooting
Section titled “5. Troubleshooting”401 Unauthorized
Section titled “401 Unauthorized”Your connection is missing, incorrect, or revoked.
- Re-run your client’s OAuth sign-in to obtain a fresh connection (in Claude Code, run
/mcpand sign in again). - GUI clients (Claude Desktop, claude.ai): remove and re-add the integration to restart the OAuth flow and obtain a fresh connection.
Tool returns “not an enabled repository” or “has no coder installation”
Section titled “Tool returns “not an enabled repository” or “has no coder installation””The call failed with an error result naming the repository: it isn’t enabled in your organization, or your organization isn’t connected to its code host.
- Go to Account → Tenants → your tenant → Repositories (
/account/tenants/:tenantId/repositories) and confirm the repository is enabled and your GitHub organization is linked. - Confirm you are a member of the Colony Cloud org (not just a GitHub org member).
GET /mcp Returns 405
Section titled “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
Section titled “Tool returns “No VCS connection” error”Tools that act on a repository need a GitHub App installation in your org. If you see errors like No GitHub App installation found for org "owner" (from colony_create_draft) or repository "owner/name" has no coder installation for this org (from the other tools), install the Colony GitHub App from Account → Tenants → your tenant → Repositories.
OAuth: browser consent screen never opened (Claude Desktop / claude.ai)
Section titled “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/apiprefix). - 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
Section titled “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
Section titled “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.