# 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

```bash
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:

```bash
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](/docs/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](/docs/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/cli).

## Docs for agents

- Every docs page is available as Markdown at its URL plus `.md`, e.g. [/docs/agents.md](/docs/agents.md).
- [/llms.txt](/llms.txt) summarizes keel.run for language models and links every page.
- [/llms-full.txt](/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.
