Interfaces

Coding agents & MCP

Give Claude Code, Codex, Cursor, or any agent a direct, safe connection to where your application runs — through MCP or the CLI, with the same context you have and the controls you choose.

With the CLI

Agents use the Apprail CLI and the REST API with a scoped, short-lived token. Everything they need is available as structured JSON:

What an agent runs

apprail capabilities --json       # what this platform can do
apprail inspect --json            # read apprail.yml and the project
apprail plan --json               # what a deploy would change
apprail deploy shop/web --image …  # ship
apprail diagnose shop/web --json  # why it is (or isn’t) healthy
apprail logs shop/web --tail 200

Point your agent at the machine-readable API description at https://console.apprail.io/api/openapi.yaml and the JSON schema for apprail.yml at /api/apprail.schema.json.

MCP server

The CLI includes an MCP server. It runs on your machine, signs in the same way as the CLI, and gives your agent 28 small, typed tools over the Model Context Protocol — no shell parsing, and the same permissions and approvals as everything else.

Claude Code

claude mcp add apprail -- apprail mcp

Cursor (.cursor/mcp.json)

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

Codex (~/.codex/config.toml)

[mcp_servers.apprail]
command = "apprail"
args = ["mcp"]

It uses the token from apprail login, or APPRAIL_TOKEN if the agent’s MCP settings set one — the best choice is a Coding agent token. If your editor can’t find apprail, give the full path, such as ~/.local/bin/apprail. Add --read-only to offer only tools that change nothing.

Tools	What they do
whoami, capabilities, list_projects, list_services, service_status	Find your way around the workspace
diagnose, logs, metrics, traffic, get_deployment, get_build, get_run, get_release, recent_activity	Understand what is happening and why
list_variables, list_resources, plan	See configuration and data — variable names only, never values
deploy_image, build, wait_for_deployment, promote, release, rollback	Ship and undo, through the normal health-checked path; release ships several services in order
run_command, update_service, set_variables, create_service, create_resource	Run migrations and scripts, and set things up

The MCP server can’t delete anything, never returns variable values, and can’t approve deployments. A deploy to a protected environment comes back as waiting for approval, and the agent is told to stop and ask you.

Tokens, scope, and approval

Create a token in the console under Settings → API tokens:

Setting	Choose	Effect
Used by	Coding agent	Expires within hours (8 by default, 7 days at most) and is marked as an agent in Activity
Access	Deploy	Can deploy, build, promote, roll back, and run jobs — and nothing else: no deleting, no variables, no members
Access	Read	Can look but change nothing — ideal for diagnosing

Give it to the agent

export APPRAIL_TOKEN=ar_…
apprail whoami

To keep production under your control, open Environments and choose Require approval for production. Deployments there from tokens, agents, CI, or git pushes then wait until an owner or admin approves them in the console, where they see exactly what changes. Tokens can neither approve nor remove the protection.

More on roles and token access in Team & access. Every change an agent makes appears in Activity, marked as the agent and the token it used; filter with apprail activity --by agent.

Teach your agent once

Add a few lines to the file your agent reads at the start of every session — AGENTS.md, CLAUDE.md, or your editor’s rules file:

## Deploying
This app runs on Apprail (project `shop`, services `web` and `worker`).
- Use the `apprail` CLI; APPRAIL_TOKEN is set. Prefer --json output.
- Before deploying: `apprail plan --json`. After: `apprail diagnose shop/web --json`.
- Deploy to staging first (--env staging); production needs a person's approval.
- Never print variable values. Read logs with `apprail logs shop/web --tail 200`.
- Docs: https://apprail.io/docs/

A good first prompt

Prompt

Deploy this repository to Apprail project shop, service web.
Use the apprail CLI (APPRAIL_TOKEN is set). Run `apprail plan --json` first and
show me the plan. After deploying, run `apprail diagnose shop/web --json` and
give me the live URL, or explain what is wrong.