MCP server

apco mcp runs an MCP (Model Context Protocol) server on stdio, exposing APCO Cloud as typed tools for Claude Code, Cursor, and any other MCP client. It speaks the MCP protocol on stdout (no JSON envelope); diagnostics go to stderr.

Setup

The server config is the same everywhere — run the apco binary with the mcp argument:

{ "command": "apco", "args": ["mcp"] }

Claude Code

claude mcp add apco -- apco mcp

Claude Code (.mcp.json)

{
  "mcpServers": {
    "apco": { "command": "apco", "args": ["mcp"] }
  }
}

Cursor (~/.cursor/mcp.json)

{
  "mcpServers": {
    "apco": { "command": "apco", "args": ["mcp"] }
  }
}

The apco CLI must be installed and on PATH. For headless environments, pass the token through the server's environment, e.g. { "command": "apco", "args": ["mcp"], "env": { "APCO_TOKEN": "apco_..." } }.

Authentication

Tools resolve credentials lazily, per call, so the server always starts and lists its tools even when unauthenticated. Resolution order:

1. APCO_TOKEN environment variable (takes precedence — use this for CI/headless).
2. The stored CLI login in ~/.config/apco/config.json (created by apco login).

An unauthenticated tool call returns a CLOUD_NOT_LOGGED_IN tool error telling the agent to run apco login or set APCO_TOKEN. Tool errors carry the same code + hint text as the CLI envelopes, and known secrets are scrubbed from error text.

Tools

Every project-taking tool requires project — a slug, id, or exact unambiguous name (get them from list_projects). Only deploy treats project as optional, falling back to the directory's manifest. span is "1h" | "24h" | "3d" | "7d" | "90d" | "all" (server default applies when omitted).

Tool	Arguments	Purpose
whoami	—	Authenticated account (id, email, name, plan).
list_projects	—	All projects: id, name, slug, type, url, latest deployment status, password protection, suspension state.
project_status	project	Latest production deployment (id, status, error, timestamps), recent deployments, public url, and command-free manifest metadata.
cluster_nodes	—	Admin-only, read-only node status, heartbeat, version, capabilities, and safe capacity. Never returns credential/key material.
cluster_node	node	Admin-only safe assignments, task outcomes, reservations, cleanup counters, and lifecycle events for an exact id or display name discovered through cluster_nodes.
deploy	path?, project?, prod?, preview?	Deploy like the CLI. Source manifests pack/upload; dockerimage sends JSON and returns safe digest provenance. A database-enabled deploy preflights the effective branch; forced channels are exact, while unforced requests leave deployMode authoritative. Configured release state is returned safely under deployment.release. Requires project-read access; no-read/deploy-only and ci:deploy credentials must use direct CLI/HTTP.
registry_credentials	project	List configured registry hosts/timestamps for an OCI project. Metadata only—never usernames, passwords, tokens, or ciphertext. Use CLI/dashboard to set or remove credentials.
build_logs	project, deploymentId?, lines?	A deployment's build log (default: the latest deployment). Use after a failed deploy.
runtime_logs	project, lines?	The running container's recent log lines (SSR apps; default 200).
metrics	project, span?	Request/traffic metrics (counts, bytes in/out) over a time span.
analytics	project, span?	Web analytics: top paths, top referrers, status-class breakdown, visitors per day.
env_list	project	Environment variable names only — values are never returned by this server.
env_set	project, key, value	Set one env var (the value is not echoed back). Redeploy/rollback for it to take effect in SSR apps.
env_delete	project, key	Delete one env var.
start	project	Start a stopped project and wait until running.
stop	project	Stop the running deployment (url serves 503 until started) and wait until stopped.
rollback	project, deploymentId?	Roll back to a previous deployment (default: latest superseded) and wait for it to run. Historical release commands are skipped. Long-running.
promote	project, deploymentId?	Preview artifact → Production. Uses the Production DB, never copies Preview data, and runs a configured release command as a fresh Production phase.
rename	project, newSlug	Rename the slug (zero-downtime, waits until live). The public url changes.
set_password	project, password	Protect the public url with a branded password page. Password not echoed back.
clear_password	project	Remove password protection.
db_status	project, channel?	Selected branch status (Production default). Never returns credentials.
db_enable	project, engine?	Production-only compatibility provisioning tool. engine is used only for the project's first branch.
db_branch	project, channel, engine?	Idempotently create an empty Production/Preview/Dev database. The first branch fixes postgres or mariadb for the project.
db_query	project, sql, rollback?, channel?	SQL as the selected tenant role. Postgres supports rollback dry runs; MariaDB rejects rollback: true.
db_schema	project, channel?	Selected branch schema.
db_usage	project, channel?	Selected branch size/read-only/connections/history.
db_migrations	project, channel?	Selected branch _apco_migrations rows.
db_backup_list	project, channel?, allChannels?	Production default or all-channel discovery; options conflict when both explicit.
db_backup_create	project, channel?	Back up one branch and poll; quotas/concurrency are project-wide.
db_backup_delete	project, backupId, confirm, channel?	Delete by authoritative ID; optional channel assertion.
db_rotate_credentials	project, confirm, channel?	Rotate only the selected role.
db_disable	project, confirm, confirmSlug, channel?	Permanently drop only the selected branch.
domains_list	project	Custom domains with verification status, routingTarget, and the DNS records each needs. Pro plan.
domains_add	project, domain	Attach a custom domain and start verification; returns the DNS records to create. Pro plan.
domains_set_routing	project, domain, routingTarget	Route a domain to Production, Preview, or Dev, or disable it while retaining verification.
domains_verify	project, domain	Re-run verification now for an attached domain (by hostname, not id). Pro plan.
dev_sync_status	project	Dev-channel status: local/sync/production urls (dev-<slug>.<domain>) and the active dev deployment, if any.
scheduled_jobs_list	project, channel?, deployment?	Safe definitions and limits; exact deployment disambiguates PR Preview scopes.
scheduled_jobs_run	project, name, channel?, deployment?	Queue one immediate manual logical run.
scheduled_jobs_set_enabled	project, name, enabled, channel?, deployment?	Persist the scheduling override.
scheduled_job_runs	project, filters	Cursor-paginated safe logical history.
scheduled_job_run_detail	project, runId	One logical run plus safe attempt metadata.
scheduled_job_logs	project, runId, attempt?	Redacted attempt logs; needs jobs:read and logs:read.
scheduled_job_cancel	project, runId	Idempotently request cancellation by stable logical run id.
delete_project	project, confirm	Permanently delete a project and all its deployments. Refuses to run unless confirm is true.

Behavioral notes

• env_list returns names only. No MCP tool ever returns env-var values or database connection strings — by design, so tool output is always safe to keep in an agent transcript.
• Database channels and engines are explicit. Optional channel defaults to Production; every selected-branch result names its channel and engine. engine may select Postgres or MariaDB only when the first branch is created and is immutable afterward. db_backup_list(allChannels: true) omits a singular result channel and every backup names its source.
• db_query is for reads. It runs arbitrary SQL as the selected tenant role. Prefer read-only SELECTs. Postgres writes can use rollback: true as a dry run; MariaDB rejects it because statements can commit implicitly.
• Confirmation-gated tools. delete_project, db_disable, db_backup_delete, and db_rotate_credentials refuse to run without confirm: true (the MCP analogue of the CLI's --yes). delete_project and db_disable additionally require confirmSlug to match the project slug.
• Long-running tools. deploy, rollback, promote, db_enable, db_branch, db_backup_create, start, and stop block until a terminal state.
• Scheduled jobs are asynchronous. scheduled_jobs_run returns a queued logical run. Poll scheduled_job_runs/scheduled_job_run_detail; commands, image references, environments, and container identities are never returned.
• OCI credentials are write-only. registry_credentials is intentionally read-only metadata. OCI deploy results may include the requested reference, resolved digest, OS, and architecture; they never include registry auth.
• Cluster diagnostics are read-only and admin-only. Project status may contain topology-safe artifact/placement state, but only cluster_nodes and cluster_node expose node identity. Node lifecycle/fencing is deliberately absent from MCP; use the confirmation-gated CLI/dashboard.
• Slug rules apply to rename: slugs starting with dev- are reserved for dev-channel hosts and are rejected.
• Not exposed over MCP (use the CLI instead): node mutations, verify, env pull/env push (file-based), db migrate, db backup download/db restore (binary streams), dev --sync, login/logout. There is no doctor tool — run apco doctor --json from the CLI.

See also

• Agent overview — when to use MCP vs CLI vs HTTP.
• Agent contract — error codes, scopes, and the JSON envelope the tool errors mirror.