Rules for AI agents
This page is the protocol an AI agent must follow when it uses the Cairn MCP tools. People should start with Let an AI assistant work with your server and Connect an AI assistant. Cursor loads the same rules from .cursor/skills/platform-mcp/SKILL.md.
Treat every rule here as a hard limit, not a suggestion.
Start of a session
- Call
platform_healthif you do not know whether the server is reachable. - Call
platform_whoamito learn whether you hold an agent token or a person's session, and which scopes you have. - Read the resource
platform://command-policy. Readplatform://openapionly when you need request shapes.
Who you are
- If
PLATFORM_AGENT_TOKENis set, you are an agent. You may use the read tools and check and run allowlisted commands, within your token's scopes. platform_logincreates a person's session in the same MCP process. Use it only when a person gave you their credentials for this purpose. It fails for accounts with two-factor sign-in.- You must not approve or reject requests with an agent token. The API refuses it (
403). - You must not invent, guess or reuse tokens or passwords from chat logs, files or earlier sessions.
Pick the narrowest tool
| Goal | Tool |
|---|---|
| Is the server up? | platform_health |
| Who am I? | platform_whoami |
| List or inspect projects | platform_list_projects, platform_get_project |
| App logs | platform_search_logs |
| Pods and nodes | platform_list_pods, platform_list_nodes |
| One pod's logs | platform_get_pod_logs |
| Install and component status | platform_bootstrap_status |
| Audit trail | platform_audit_logs |
| API shape | resource platform://openapi |
| Which commands are legal | resource platform://command-policy and Tools and command policy |
| Run a cluster command | platform_run_command (see below) |
| Deploy an app | platform_deploy, only with a person's session and after review |
Do not use platform_run_command with kubectl get pods when platform_list_pods does the job.
How to run a command
[ draft one command ]
│
▼
platform_run_command({ command }) # no confirm
│
▼
read validation: allowed, riskLevel, matchedPolicy,
requiresConfirm, requiresReason, requiresHumanApproval, approvalId
│
├── allowed = false → stop. Explain matchedPolicy. Do not retry with confirm.
├── read, no approval → you may call again with confirm: true
├── needs a reason, no approval → tell the person, then confirm: true + reason
└── requiresHumanApproval → a person approves, then confirm: true + reason + approvalId
- Never send
confirm: trueon the first call. - Never send
confirm: truewithout showing or summarising the validation result to the person. - Never chain commands: no
&&,|,;, backticks or$(. One command per call. - Put the subcommand right after the program name:
kubectl get pods -n platform, notkubectl -n platform get pods. - Do not use flags that switch cluster or identity (
--kubeconfig,--server,--token,--asand similar). They are refused.
Commands that need a person
These need approval: kubectl delete, drain, cordon, uncordon, apply, create, patch, edit, scale; helm upgrade, install, rollback, uninstall, delete, get; platformctl destroy, teardown, reset; and any kubectl get that prints secret contents.
Sequence:
platform_run_command({ command }). The result hasrequiresHumanApproval: trueand anapprovalId.- Tell the person exactly what will change and wait.
- The person approves in the portal (project page, Monitoring, AI agents, Waiting for approval), or in this session with
platform_login,platform_list_pending_commands,platform_approve_command. platform_run_command({ command, confirm: true, reason, approvalId })with the exact same command.
Facts to respect:
- An approval works only for the token (or person) that asked, only for that exact command, only once, and only for one hour.
- Checking the same command again while it is still pending returns the same
approvalId. Do not loop on validation; ask the person to act. - The confirm call checks the command again, which opens one more pending request. Mention it to the person; they can reject it.
- If no one can approve in this session, stop and ask the person to approve in the portal. Never work around the queue.
Deploys
platform_deploy needs projectId and confirm: true. The API refuses agent tokens for deploys, so it works only with a person's session from platform_login (Developer, Tech lead, DevOps or Admin) and with no PLATFORM_AGENT_TOKEN set. Before confirming, check the environment (environmentId or environmentName), branch and image tag with the person. A production deploy needs an explicit go-ahead from the person in the conversation.
What you must not do
- Approve your own requests, or ask for an approval you do not need.
- Put passwords or
plat_agent_*values in git, tickets, chat summaries or screenshots. - Try
rm -rf /,dd,mkfs,DROP DATABASE, fork bombs or sending secrets out. They are refused even if a person asks; refuse and cite the policy. - Turn off authentication or RBAC, or delete cluster roles or role bindings.
- Call
curlorwgeton hosts other thanlocalhost,127.0.0.1,ghcr.ioorgithub.com. (These programs are not on the allowlist anyway.) - Say a command ran when you only validated it. Check
phase: "execution"andresult.okin the answer.
Reading results
phase: "validation"means nothing ran.phase: "execution"containsresultwithok,exitCode,stdout,stderr,durationMs.result.dryRun: truemeans the server only simulated it.- Secrets in results appear as
[REDACTED]. Do not try to recover them.
Errors
| Status or field | What to do |
|---|---|
401 |
Ask for PLATFORM_AGENT_TOKEN or a platform_login. Do not retry blindly. |
403 |
Missing scope, too low a role, refused command, or an approval that is not approved yet, expired or belongs to someone else. Explain and escalate to a person. |
409 |
The approval was already used or changed state. Validate again only if the person wants to retry. |
400 |
Add the missing confirm or reason, or use the exact command that was approved. |
504 |
The call timed out. Check status with a read tool before retrying a change. |
matchedPolicy: no-matching-policy |
The command is not allowlisted. Use an allowed form or a dedicated tool. |
matchedPolicy: deny-shell-chaining |
Split it into separate single commands. |
Example: read only
platform_health()
platform_whoami()
platform_list_pods({ namespace: "platform" })
platform_run_command({ command: "kubectl get deploy -n platform" })
# show the validation result
platform_run_command({ command: "kubectl get deploy -n platform", confirm: true })
Example: restart a deployment
platform_run_command({ command: "kubectl rollout restart deploy/platform-api -n platform" })
# show the result, wait for the person to agree
platform_run_command({
command: "kubectl rollout restart deploy/platform-api -n platform",
confirm: true,
reason: "pick up rotated secrets"
})
Example: delete a pod
platform_run_command({ command: "kubectl delete pod web-7d9f -n my-app" })
# → requiresHumanApproval: true, approvalId: "a1b2..."
# tell the person; wait until they approve in the portal
platform_run_command({
command: "kubectl delete pod web-7d9f -n my-app",
confirm: true,
reason: "pod stuck in CrashLoopBackOff, person approved",
approvalId: "a1b2..."
})
How it works
- Commands are checked by the API, not by the MCP server. The rules live in
platform/api/src/lib/command-guard.ts. Refusal rules are checked first, then the allowlist. - The command is split into arguments without a shell and run with
execFileinside the API pod, so shell features never apply. - Approval routes require a person's session (
requireHumanJwt); agent tokens get403.