MCP server

Coming soon

The Koo MCP server exposes your account to any MCP host — Claude Code, Codex, Cursor — as a set of koo_* tools. Through it, an agent can deploy a service, follow the deployment timeline to ready, roll back, tail logs, read metrics, set variables, and check status — without leaving the agent.

It authenticates with a single API token (kc_…), scoping the agent to exactly one account and one role. The server never adds an account switch — the token is single-account by construction. Permissions are enforced by the API, not the agent: a reader token can watch a deploy but never start one.

The server is code-complete and verified in the Koo monorepo, but the @koo-io/mcp-server package is not published to npm yet, and the koo mcp CLI command ships with the next CLI release. Until both land, drive Koo from an agent over the plain REST API with a kc_… token. The commands below are what will install it.

Install

One command registers the server and its matching skill in your host:

text

koo mcp install claude-code   # or: codex, cursor

The install writes a host config block that launches the server with koo mcp run — no token is ever written into it. Your kc_… token is stored in your OS keyring and injected only at launch. Re-running the install is idempotent, and koo mcp uninstall <host> removes exactly what it added.

Tools

Every tool returns structured content and acts on the single account the token is bound to. Reads are marked read-only; writes (koo_deploy, koo_rollback, koo_set_variables, and the creates) carry a destructive hint so your host can prompt before applying.

Tool	Access	What it does
`koo_whoami`	Read	The account and role the token is confined to (its blast radius).
`koo_list_projects`	Read	The account's projects.
`koo_list_environments`	Read	A project's environments.
`koo_list_services`	Read	An environment's services, each with its health and URL.
`koo_get_service`	Read	One service's full configuration and status.
`koo_service_status`	Read	A compact health/applied/build rollup for a service, plus any failures.
`koo_list_deployments`	Read	A service’s deployments, newest first — status + per-phase timestamps (the timeline).
`koo_get_build_logs`	Read	The build output for one from-source deployment version.
`koo_get_logs`	Read	Recent runtime logs, over the resolved (plan-clamped) window.
`koo_get_metrics`	Read	A metric series (cpu/mem/req/latency) over the resolved (plan-clamped) window.
`koo_get_variables`	Read	A service’s effective variables — source scope, sensitivity, kind, shadowing, and dangling refs.
`koo_deploy`	Write	Ship a deployment — pin an image, or omit it to redeploy the configured source.
`koo_rollback`	Write	Roll a service back to a prior deployment version.
`koo_set_variables`	Write	Set or unset a service’s variables via a merge batch (literal name→value; the server merges).
`koo_create_project`	Write	Create a project (with a default environment).
`koo_create_service`	Write	Create an exposed web service from a prebuilt container image.
<!-- mcp-tools:end -->

koo_get_logs and koo_get_metrics return the window actually queried after it is clamped to your plan's retention — the agent reports that resolved window and does not retry to widen it. Deploying from local source is not a tool: the skill routes that through koo up in the CLI, then watches the result with these tools.

Security

Least privilege. Mint an editor token to deploy and manage, or a reader token for read-only agents — never admin. Roles are enforced by the API.
Single-account scope. A kc_… token is bound to one account; the server exposes no way to reach another. The account and role are visible via koo_whoami so you can see the blast radius.
Visible and revocable. Each token shows its lastUsedAt, so a stale one is obvious, and you can revoke it any time from the token list in the console.
No token in config. The install references your token by keyring entry only, never as a literal in a host config file or a skill.

Until then

Drive Koo from any agent through the plain REST API with a kc_… token today.
See Deploy with AI for the end-to-end agent deploy flow, and AI skills for the installable skills that ship alongside this server.