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