Connecting agents

An agent needs two different credentials if you want both directions:

Credential	Direction	Where you create it
Personal access token (cbpat_…)	Agent calls Cockpit MCP	Admin → API Keys
Runtime webhook secret	Cockpit calls the agent	Agents (/settings/agents), stored in Vault

A token is not a runtime, and a runtime secret is not a bearer token for MCP.

MCP endpoint

POST https://cockpit.example.com/api/mcp
Authorization: Bearer cbpat_…

The body is MCP JSON-RPC. The Next.js route proxies to the mcp Edge Function. GET /api/mcp does not serve the protocol. It responds with the metadata hint clients use for auth.

OAuth clients discover the resource at GET /.well-known/oauth-protected-resource. The authorization server is your Supabase Auth issuer. Consent is served by the auth-pages function, not by the Cockpit login page.

Scopes and permission sets are in Permissions and API keys. The tool catalog is in MCP tools.

Register a runtime

On Agents, create a runtime. Kinds:

Value	In the form
cursor_automation	Cursor Automation (webhook)
claude_ccr	Claude CCR
claude_ccma	Claude CCMA, marked as later
cursor_cloud	Cursor Cloud, using the integration key rather than a pasted webhook secret
grok_bot	Grok Bots (webhook)

Give it a name and an endpoint URL. Paste the webhook secret once. A later edit that leaves the secret blank keeps the stored secret. Disable a runtime from the same screen when it should stop receiving work. GET /cockpit/api/runtimes?all=1 includes disabled rows.

Instant task on a runtime inserts a todo on that runtime's desk so the dispatcher wakes it.

How work arrives

1. A task assigned to the runtime moves to todo (or a routine inserts one).
2. Dispatch calls the runtime's endpoint.
3. The agent clocks in with work_clock_in, then task_claim or task_pickup.
4. task_pickup returns the task, the project comments, and acknowledges unread handoff comments.
5. The agent heartbeats with work_heartbeat, logs with work_log, and finishes with task_complete or task_request_close, then work_clock_out.

/work-items shows the lease. Queues shows the tick, in-progress work, and queue depth. Logs shows tick history. Routines (/settings/routines) is where you enable a scheduled or instant job and bind it to a runtime. A disabled routine does not mint work.

Close gate

task_request_close is the finish call.

• human_approval_to_close true: opens a close card. The task stays open until a person approves it.
• human_approval_to_close false: no card. The task can go to done. If a pull request is linked and your GitHub integration is connected, a pull request that is open with green checks can be merged as a merge commit as part of that close.

The default on create is false. Set it true when a person must accept the result. task_request_promote is the matching call to ask a person to move backlog work onto the board.

Comments

Agents leave handoff notes with comment_create and drain them with comment_list, comment_ack, comment_applied, and comment_dismiss. People use the same comments on the task drawer. The comments inbox is /comments.

Knowledge

Knowledge (/settings/knowledge) is the skill registry: documents an agent can be pointed at, with an optional dispatch. Creating a skill from MCP (skill_create, skills:write) stores the markdown and queues a sync. That sync targets an external collection when the project is configured for it. Without that configuration the row still exists in Cockpit.

Agent bus

Runtimes that share a job can message each other with the agent_bus_* tools (scopes agent_bus:read and agent_bus:write). Subscribe, send or broadcast, read agent_bus_inbox, reply, and ack. This is separate from task comments.