Get started

Agents and MCP

keel.run treats coding agents such as Claude Code as first-class users: an agent can do everything a person can – but only what you allow, and everything it does is in the audit log.

Way For Sign-in
MCP server https://mcp.keel.run/mcp agents with MCP support (Claude Code, Claude Desktop, Cursor, …) OAuth 2.1 in the browser, with a consent page
CLI keel terminals, scripts, CI, agents with a shell keel login or KEEL_TOKEN
API https://api.keel.run/v1 everything else Authorization: Bearer keel_…

Agents use the CLI only with an agent token: create one with keel tokens create --kind agent --scopes read,deploy (or in the dashboard) and give the agent KEEL_TOKEN=keel_agent_…. When CLAUDECODE or KEEL_AGENT is set, the CLI refuses personal tokens and your own keel login, so the workspace's approval rules always apply to agents.

Connect Claude Code

claude mcp add --transport http keel https://mcp.keel.run/mcp

On the first tool call (or with /mcp → Authenticate), Claude Code opens your browser. Sign in to keel.run and choose:

  • the workspace – a connection always belongs to exactly one workspace,
  • optionally some projects – empty means all projects,
  • the permissions (scopes, see below) – preselected is what the client asks for; admin is never preselected,
  • the expiry – 1, 7, 30 or 90 days.

The agent then gets an access token (keel_agent_…, valid for one hour) and a refresh token (30 days, at most until the expiry you chose). The refresh token changes on every use; if an old refresh token is ever used again, keel.run revokes the whole connection, because that means it was stolen.

To disconnect, revoke the token "Claude Code (OAuth)" in the dashboard under Settings → Tokens, or run claude mcp remove keel.

Other MCP clients

Any client with Streamable HTTP and OAuth (dynamic client registration and PKCE) works. Clients without OAuth can send an agent token created in the dashboard as a header:

claude mcp add --transport http keel https://mcp.keel.run/mcp --header "Authorization: Bearer keel_agent_…"

The MCP server accepts only agent tokens (keel_agent_…), not personal or CI tokens.

Tools

Tool Scope Purpose
list_projects read projects with environments and services – start here to find IDs
get_service read a service, its latest deployments, runtime status and domains
list_deployments read deployments, newest first, paged with cursor
get_deployment read (+ logs:read for log_lines) a deployment's status, optionally the end of its build log
diagnose_deployment logs:read why a deployment failed or is unhealthy: phase, cause (e.g. port_mismatch, missing_env_var), relevant log lines, concrete fixes
get_logs logs:read runtime or build logs, at most 500 lines, with a filter
list_databases read databases of an environment
list_previews read preview environments of a project's pull requests, with status and URLs
deploy_service deploy deploy the branch head, a commit or an upload (upload_id); waits up to wait_seconds and returns the diagnosis of a failure
deploy_upload deploy deploy a local directory: returns the CLI command and optionally a one-time upload URL
rollback_service deploy go back to an earlier deployment (default: the previous one)
restart_service deploy restart the instances
set_variables config:write (+ deploy to roll out) set or delete variables (null deletes)
update_service config:write + deploy change port, health check, size, instances, start or release command, builder, Dockerfile, root, branch; redeploys
get_approval read status of a request that waits for a person's approval
run_command deploy + config:write run a command once with the service's image and variables (migrations, seeds); returns status, exit code and output
get_run read (+ logs:read and config:write for the output) status, exit code and output of a one-off or cron run; output can contain secret values, without both permissions it is hidden (output_redacted)
list_runs read runs of a service, newest first
create_database databases:write create a Postgres database
get_database_url databases:read connection URL with password
run_sql databases:query one SQL statement in a read-only transaction, with a row limit
list_kv read serverless Valkey (KV) databases of an environment
create_kv databases:write create a KV database
get_kv_credentials databases:read rediss:// URL, REST URL and token (Upstash-compatible), internal URLs
add_domain domains:write add a custom domain; returns the DNS records to create
list_dns_zones, get_dns_zone read keel DNS zones: status, nameservers for the registrar, delegation check, DNSSEC state, issues
list_dns_records, export_dns_zone read the records (RRsets) of a zone, or the zone as a BIND zone file
get_dnssec_ds read DNSSEC state and the DS record for the registrar
test_dns_query read ask keel's answer engine about the current zone, also before delegation
create_dns_zone, verify_dns_zone dns:write create a zone (returns the nameservers and what to tell the user), check the delegation now
create_dns_record dns:write add a new RRset (fails if it exists)
import_dns_zone dns:write import a zone file; mode add directly, mode replace destructive, two steps
set_dns_record, delete_dns_record, apply_dns_changes dns:write destructive, two steps; the preview shows the old and the new records
delete_dns_zone admin destructive, two steps
delete_service admin destructive, two steps
delete_database admin destructive, two steps
delete_kv admin destructive, two steps
list_mail_domains, get_mail_dns_status mail:read mail domains with their status; the DNS records with check results and a hint per problem
list_mailboxes, get_mail_log, get_mail_reputation mail:read mailboxes (never their mail), the message log of app mail (metadata only), sending reputation, holds and limits
create_mail_domain, create_mailbox, create_mail_alias mail:write add a domain (verified and configured at once when its zone is in keel DNS), a mailbox, an alias or the catch-all (*)
set_mail_forwarding mail:write forward a mailbox; needs approval where approvals are on, and the mailbox owner is notified
create_sending_key mail:write a key for app mail, returned once (store it as secret variables)
delete_mailbox, delete_mail_domain admin destructive, two steps
reset_mailbox_password mail:write destructive, two steps: removes the mailbox password and revokes every app password; the agent gets no new credential

No tool sends mail, reads mail or hands out mailbox credentials: a prompt injection could otherwise send spam or read your mailboxes.

A typical loop: list_projects → deploy_service → poll get_deployment until active or failed → on failure diagnose_deployment → apply a suggestion (update_service, set_variables, or fix the code) → deploy again.

A workspace can also require a person's approval for actions of agent tokens (every deletion, restores and credential rotations, or every change). Held requests answer 202 with an approval_id; poll get_approval until the request ran, and never send it again.

Confirmations for destructive actions

Destructive tools never delete on the first call. They return a preview of what would be deleted and a confirmation_token. Only a second call with exactly this token deletes. The token is valid for 5 minutes, works once, and is bound to the action, the target, the person and the workspace. For DNS changes it is also bound to the exact records and to the zone's version at the time of the preview: if the zone changed in between, the agent has to ask again. The tool descriptions tell the agent to show you the preview and to confirm only after you agreed.

Errors carry a code and a hint, for example: missing_scope: … Hint: ask the user to reconnect keel.run and tick "deploy".

Scopes

Scope Allows
read read projects, services, deployments and settings
logs:read build and runtime logs
deploy deploy, roll back, restart
config:write change configuration and variables, read secret values, start runs and (with logs:read) read their output
databases:read databases and connection URLs (with password)
databases:write create and change databases
databases:query read-only SQL
domains:write add and remove domains
dns:write keel DNS: create and change zones and records (deleting a zone needs admin)
billing:read billing and usage
admin everything, including deletion and token management (destructive)

A good default for an agent that ships code: read, logs:read, deploy. Add config:write if it should manage variables, databases:query if it should look at data.

A connection never has more rights than the person who granted it, and keel.run checks the person's current role whenever the token is refreshed. If the person loses access to the workspace, the connection ends.

The CLI for agents

Agents with a shell can use the CLI instead of MCP:

  • Every command takes --json: stable JSON on stdout, progress and logs on stderr. Errors are {"error": {"code", "status", "detail", "hint", "request_id", "exit_code"}} on stderr.
  • Without a terminal, commands that would ask for confirmation fail with exit code 2 unless you pass --yes.
  • Exit codes: 0 ok, 1 error, 2 usage or not linked, 3 not logged in, 4 forbidden (role, scope, plan, billing), 5 not found, 6 invalid or conflict, 7 temporary (retry later), 8 deployment failed, 130 interrupted.

See the CLI reference.

Docs for agents

  • Every docs page is available as Markdown at its URL plus .md, e.g. /docs/agents.md.
  • /llms.txt summarizes keel.run for language models and links every page.
  • /llms-full.txt contains the whole documentation in one file.

Security

  • OAuth 2.1 with the authorization code flow and PKCE (S256) only; public clients without secrets; exact redirect URIs (https, or loopback where only the port may differ); codes are valid for 60 seconds and once.
  • Tokens for the MCP server are bound to https://mcp.keel.run/mcp (RFC 8707 resource indicators). The MCP server refuses tokens for other resources, and the API refuses MCP tokens that do not come through the MCP server.
  • The consent page is protected against CSRF and framing and runs no scripts.
  • Codes, refresh tokens and tokens are stored as hashes. Creating, refreshing and revoking is recorded in the audit log with the client's name.
  • Dynamically registered clients are rate-limited per IP address and removed after 90 days without use.

View as Markdown