Skip to content

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.

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

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.

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.

Terminal window
claude mcp add --transport http colony https://app.runcolony.com/mcp

Then 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.

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

{
"mcpServers": {
"colony": {
"url": "https://app.runcolony.com/mcp"
}
}
}
  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.
  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.

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

ParameterValue
Endpointhttps://app.runcolony.com/mcp
MethodPOST only — GET returns 405
AuthOAuth 2.1 — the client discovers the metadata and runs the flow (see below)
Content-Typeapplication/json
Acceptapplication/json, text/event-stream
SessionsStateless — 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" }
}
}

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.

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.

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.

  • 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 from GET /api/orgs/{orgId}/connections?mine=true.
  • Holders of the org-connection-revoke-any grant also see every connection in the organization in Account → Connections, with the person each app acts as.

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 baseline scope, or “Reads and acts on work” once work is 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.

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.

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 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.

Removing a member revokes their connection tokens in this organization. Signing a member out does not. See Team & Roles.

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": {}
}

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

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 baseline connection, 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 with requires 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.
ToolR/WScopeGrantDescriptionRequired inputsOptional inputs
colony_workReadBaseline—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 scrubbedviewrepo, 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_issueWriteWorkvcs-writeFile and enqueue an issue with Colony-aware formatting; applies colony:enqueue and optional complexity/epic labelsrepo, title, bodyas_epic, complexity_hint (small/medium/large), assignees, constraints (array)
colony_estimateReadBaseline—Cost and time estimate before filing; returns estimated cost (USD), confidence, and historical examplesrepo, descriptioncomplexity (small/medium/large)
colony_reviewReadBaseline—Get Colony’s review verdict on a change; returns verdict, structured findings, and review costrepo, change_number—
colony_actWriteWorkPer action, see colony_act actionsPerform an operator action on a work item. action selects the operationrepo, issue_number, actionDepends on the action
colony_tracksReadBaseline—List self-improvement tracks for a repo; shows completion counts, cooldown status, and active issuerepo—
colony_import_planWriteWorkvcs-writeImport 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 titlerepo, tasks (array of task objects: key, title, body, dependsOn, needsHuman, crossRepo)dry_run, as_epic, initial_state, epic_title, epic_body, assignees, constraints
colony_intelligenceReadBaseline—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 receiverepomode, 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_workflowsReadBaseline—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 insteadrepoworkflow_id, version, tenant_id
colony_flaky_checksReadBaseline—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 quarantinedrepodays (1–90, default 14), limit (1–50, default 10)
colony_strategyWriteWorkAutonomyOperate 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: messagerepo, action (generate/approve/reject/revert/list/get)version, edits, reason, status, limit, confirm

Five tools exist only in Colony Cloud. They run against your Cloud data rather than the pipeline.

ToolR/WScopeGrantDescriptionRequired inputsOptional inputs
colony_create_draftWriteWorkvcs-writeCreate 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 firstrepo, title, bodykind (string, 1–64 characters, taken from the repo’s workflow; defaults to none), source_metadata (object: calling_tool, conversation_summary, session_id)
colony_queueReadBaseline—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_standardsReadBaseline—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 auditedrepo—
colony_reportReadBaseline—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_reposReadBaseline—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 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.

ActionExtra inputsrequest_idconfirm: trueGrant
pause—NoYesvcs-write
resume—NoNovcs-write
cancel—NoYesvcs-write
retrysize (small/medium/large, optional)Optional (generated when omitted, and returned)Novcs-write
reimplementtext (optional; adoption instructions on a Dependabot tracking issue)RequiredYesvcs-write
adopttext (instructions that build on a Dependabot update)RequiredYesvcs-write
followuptext (on a Dependabot tracking issue; omit it on an epic)RequiredNovcs-write
reanalyze—NoNovcs-write
reopen—NoNovcs-write
releasechild_numberNoYesvcs-write
invokeintent, expected_head_sha (optional)NoYesvcs-write
answertextRequiredNovcs-write
pickchoice, round_id (optional)RequiredNovcs-write
constraintextRequiredNovcs-write
constraints— (read-only: lists the item’s standing constraints and their ids)NoNovcs-write
unconstrainconstraint_idRequiredNovcs-write
feedbacktextRequiredNovcs-write
review—RequiredNovcs-write
prioritylevel (high/normal/low)RequiredNovcs-write
enqueuelevel (high/normal/low, optional)OptionalNovcs-write
skip-planning—RequiredNoOperations
decompose—RequiredYesvcs-write
statetarget_state, reasonRequiredYesOperations
unblock—RequiredNoOperations

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 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.

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.

ToolRemoved inputUse instead
colony_workpr_numberchange_number
colony_worklabelworkflow or trait
colony_reviewpr_numberchange_number
colony_file_issuelabelsas_epic
colony_strategygovernedNothing: strategy tracks are never governed

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.

Input:

{ "view": "status", "repo": "RunColony/colony" }

Output:

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

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.

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": []
}

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'" }] }

Your connection is missing, incorrect, or revoked.

  • Re-run your client’s OAuth sign-in to obtain a fresh connection (in Claude Code, run /mcp and 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).

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.

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 /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.
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.

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.