Coroid as an MCP server

Coroid exposes a remote Model Context Protocol (MCP) server. An external assistant or agent, such as Hermes, Codex or Claude Code, can use it to work with Coroid through the same governed tool registry the chat assistant uses.

Configure under Settings → Connections → Coroid MCP server, which covers Overview, Client setup, Access tokens, Approvals and Automation policies.

The endpoint#

The MCP server runs on the API gateway, at this address:

https://api.coroid.ai/mcp

The transport is stateless Streamable HTTP. Authenticate with OAuth or a personal access token.

What is switched on#

Coroid switches MCP capabilities on in stages, for every organization at once.

Until a capability is on, clients do not see its tools and Coroid refuses calls to them. The rest of this page describes the full set.

Connect a client#

Use OAuth when your client supports it. You approve the connection in your browser and can revoke it at any time. Access tokens last 15 minutes and refresh tokens 30 days, and each refresh replaces the refresh token.

The client asks for scopes when it connects. Before you approve, you see the scopes and choose whether the client can reach every project or only some. A client that asks for no scopes gets read access only, so ask for the scopes you need, as the Codex example does.

Hermes#

hermes mcp add coroid --url https://api.coroid.ai/mcp --auth oauth
hermes mcp login coroid
hermes mcp test coroid

With an access token instead:

hermes mcp add coroid --url https://api.coroid.ai/mcp --auth header

Give Hermes the token when it asks for one. Keep it in Hermes' credential store rather than its configuration file.

Codex#

codex mcp add coroid --url https://api.coroid.ai/mcp
codex mcp login coroid --scopes mcp.read,mcp.work.write,mcp.execute,mcp.delivery

With an access token instead:

export COROID_MCP_TOKEN="cmp_pat_…"
codex mcp add coroid --url https://api.coroid.ai/mcp --bearer-token-env-var COROID_MCP_TOKEN

Claude Code#

claude mcp add --transport http --scope user coroid https://api.coroid.ai/mcp
/mcp

Run the first command in your terminal. Then type the second in Claude Code, choose coroid and sign in in your browser.

With an access token instead:

export COROID_MCP_TOKEN="cmp_pat_…"
claude mcp add --transport http --scope user --header "Authorization: Bearer $COROID_MCP_TOKEN" coroid https://api.coroid.ai/mcp

Other clients#

Any client that supports remote MCP servers over Streamable HTTP can connect. Coroid publishes OAuth metadata for the endpoint and supports dynamic client registration with PKCE. A client without OAuth can send an access token as a bearer token in this header: Authorization.

Before an agent changes anything, ask it to list Coroid's tools and to read this resource: coroid://context. It shows who the agent acts as, with which scopes and projects.

Access tokens#

Tokens are created and managed under Access tokens. Like every other credential, they are shown once and never returned afterwards.

Issue one token per client rather than sharing one. Revoking a single client's access is then a contained action rather than an outage for everyone.

A token acts as the person who created it, and only a person signed in to the portal can create one. Each token has its own scopes, expires after 30, 90 or 365 days, and reaches every project or only the projects you select. An owner can also attach an automation policy. Every token starts with the same prefix: cmp_pat_.

Keep a token in your client's environment or credential store. Never put it in a repository or a prompt.

Scopes and roles#

A scope says what a connection may do. Your role in the organization sets the limit: a tool needs both its scope and at least its role. Coroid checks your current role on every call, so a connection never keeps rights you have lost.

Only an admin or owner can grant a scope whose lowest role is Admin. Only an owner can grant a scope whose lowest role is Owner.

A connection limited to some projects cannot reach anything in other projects, even through the ID of a task, plan, sprint, report or release. It cannot use organization-wide tools either, such as these: list_plans, get_capacity_dashboard.

Tools#

Your client lists only the tools that are switched on and that your scopes and role allow. The approval column says what happens when a tool is called:

Reading#

These tools need the Reviewer role and this scope: mcp.read. None of them needs approval.

For the release tools, see Releases over MCP.

Creating and changing work#

These tools need the Member role and this scope: mcp.work.write.

Work created over MCP does not go through Qualification. A plan-sized request sent to the task tool becomes a draft plan instead of a task. Plans created over MCP start as drafts.

Running work#

These tools need the Member role and this scope: mcp.execute.

Delivery#

These tools need the Member role and this scope: mcp.delivery. Releases have their own section below.

Administration#

These tools change how the organization and its projects are set up.

Organization settings#

An agent such as Hermes can configure an organization from screenshots, files or a description. It reads Coroid's settings format, writes what it has into a bundle, previews the bundle and then applies it. These tools need the Owner role and this scope: mcp.organization.admin.

A bundle carries placeholders instead of secret values, and Coroid rejects a bundle that contains a secret. See Export and import settings.

Releases over MCP#

The release tools are the same ones the chat assistant uses, and they go through the same Release API as the portal:

create_release accepts a full commit SHA, a short SHA of a recent commit, or latest, and leaves the version to the project's version source unless you give one. get_release reports, per environment, the checks, the last deployment, the version your pipeline reported and whether Coroid verified the running version. A token limited to some projects cannot reach releases in other projects. The Release API still applies its own approval rules, so an approval through MCP counts exactly like one in the portal.

list_release_pull_requests returns a project's open pull requests in the order Coroid proposes, with the reason for any it would leave out. bundle_release_pull_requests creates a release from them: a release branch with the pull requests merged in order and one release pull request. It pushes a branch and opens a pull request, so it always waits for a person. Leave out prNumbers to use Coroid's selection.

Approvals and automation policies#

Approvals is a queue of actions waiting for a human. Automation policies decide what needs to be in that queue.

This is the control that matters. An external client acting on your behalf should be able to do routine things freely and consequential things only with a person agreeing. Set the policies before handing a token to anything that runs unattended.

When a call needs approval, the client gets an approval ID and a link instead of a result. An owner or administrator reviews the exact tool and arguments, then approves or rejects the call. Approving runs the call exactly as it was made, and the client cannot change it afterwards. A call that nobody approves within 10 minutes expires.

An automation policy lets an access token run tools marked Policy without waiting for approval. Only owners create policies and attach them to tokens. A policy names the exact tools, can be limited to some projects, and caps how many calls run per hour, per day and at the same time. It can also expire. Revoking a policy revokes every token attached to it. Tools marked Always are never covered by a policy.

An OAuth connection cannot carry a policy. Over OAuth, every tool marked Policy waits for approval.

Retries, operations and resources#

Every tool that changes something requires this parameter: idempotencyKey. Use a new key for each new action, and the same key when you retry one. Coroid then returns the first result instead of acting twice. A key reused with different arguments is refused.

A change also returns an operation that records its status and result. These four tools work for every connection:

The server also provides these resources:

It also offers three prompts: create_and_run_task, investigate_failure, prepare_release.

Each tool has limits per minute, per hour and per day. A call over a limit fails and says how long to wait before retrying.

What it deliberately does not expose#

The tool registry is governed, and the exclusions are intentional. It provides none of these:

• a shell
• Git access
• the filesystem
• raw database access
• arbitrary internal HTTP
• Coroid's own outbound MCP administration tools

You are getting the ability to manage work — create and inspect tasks, plans, projects and releases — not a remote execution environment. An MCP client cannot use Coroid as a way to run arbitrary commands.

What it is good for#

Driving Coroid from where you already work — an editor, an assistant, an internal tool — without switching to the portal. Creating a task from your terminal, or having an assistant check what is blocked, becomes a local action.

Related#

• Ways to start work
• Export and import settings
• External MCP servers
• Chat assistant
• Provenance