> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cowboy.inc/llms.txt
> Use this file to discover all available pages before exploring further.

# CIP-52: The User MCP Surface

> Cowboy's MCP server exposes the user-facing CLI as tools. Reads answer directly, every write is prepared by the server and signed by the owner in their own wallet, and the tool definitions come from one table in the CLI that classifies every command.

> [!NOTE]
>
> **Status:** Draft\\
>
> **Type:** Standards Track\\
>
> **Category:** Core (Dashboard)\\
>
> **Created:** 2026-11-05\\
>
> **Requires:** CIP-40 (transaction digest with signatures zeroed), CIP-33 (hires and `allow_caller`)\\
>
> **Related:** CIP-19 (Gateway MCP ingress for actors), CIP-37 (Sign in with Cowboy), CIP-48 (batched transactions)

> [!NOTE]
>
> **Cowboy Cloud and Cowboy Chain.** This CIP specifies the Cowboy protocol. Cowboy Cloud runs on this protocol today. Cowboy Chain, a public network on the same protocol, is under consideration for a future release. Where the two differ, this CIP says so.

Code citations are to the `cowboyinc/core` devnet branch and the `cowboyinc/dashboard` main branch. The key words MUST, MUST NOT, SHOULD and MAY are to be read as in RFC 2119 and RFC 8174 when, and only when, they appear in capitals.

## 1. Abstract

The dashboard's MCP server lets an outside agent act for one Cowboy owner. Today it serves the General Store only. This CIP extends it to the user-facing part of the `cowboy` CLI: the owner's balance, actors, jobs, transactions and rooms as reads, and payments as writes. The design choice the rest depends on: **the MCP server never holds an owner's key.** A write tool records an approval and returns a link; the owner opens it, the browser decodes and verifies the exact transaction, and the owner signs it in their own wallet. The one standing exception is the Store's delegated-grant path, where the owner has already named a Store caller on a hire with `allow_caller` and set the limits it spends inside.

## 2. Motivation

An agent that helps someone run software on Cowboy needs to see what they own and to start the actions they would otherwise type into the CLI. The MCP server at `/api/mcp` (`dashboard backend/src/routes/mcp.ts:1-9`) already has the pieces for one domain: OAuth sign-in that ends in an owner-approved connection (`backend/src/services/oauth.ts:1-11`), per-connection rate limits (`routes/mcp.ts:44-45`), secret scanning of free text (`services/store-mcp-tools.ts:809-824`), and an approve-in-Cowboy request for hires (`request_hire`, `store-mcp-tools.ts:275-411`). Everything outside the Store has no MCP surface, so an agent either asks the owner to run CLI commands by hand or is handed the owner's private key, which defeats the custody model.

The CLI is also the most complete description of what a user can do. It has 52 top-level commands (`core cli/src/app.rs:77-622`), many of them for operators and developers. A second, hand-written list of tools would drift from it the first time a command is added or a flag renamed.

## 3. Design Goals

* **No custody.** No MCP tool signs a transaction with an owner's key. The server builds; the owner's browser verifies and signs (§8.1).
* **One decision per approval.** A write produces one approval the owner accepts or declines on its own page, with every amount and recipient decoded from the transaction bytes.
* **User actions only.** The surface is what an owner does with their own account. Operator, validator, governance and local-development commands are excluded by rule (§6.2), and every exclusion has a reason.
* **One source of truth.** Every CLI command is classified in one table in the CLI, and tool names, descriptions and argument schemas come from it. A command or argument added to the CLI without a decision about MCP fails CI (§6.7).
* **Owner-scoped.** Every tool acts for the connection's account. No tool takes the acting account as an argument.
* **Amounts in the network's display unit.** On Cowboy Cloud every amount is US dollars at the posted rate, and CBY is never named (§6.3).
* **Revocable.** Revoking a connection ends its tools, its waiting approvals and its delegated grants together.

## 4. Non-goals

* MCP for actors. Exposing an actor's own routes as tools is CIP-19's Gateway ingress.
* Agent-held keys, session keys or spending allowances on chain. A standing agent spend exists only through the Store's delegated grants (§6.5).
* Approvals that create a standing spend: deploys that turn on owner funding, owner-funding changes and auto top-up. They are deferred (§9).
* MCP resources and prompts. The surface is tools only.
* Turning Cloud on. §7 says how it turns on; the decision is the operator's.

## 5. Definitions

* **Owner.** The Cowboy account a connection acts for: `agent_connections.account_id` and its `wallet` (`backend/src/db/migrations/0101_store_mcp.sql:1-12`).
* **Connection.** One row of `agent_connections`, made by an owner-issued `cst_` token or an OAuth sign-in (`routes/mcp.ts:174-207`). It carries the scopes of §6.6. A connection is **live** while `revoked_at` is null and `expires_at` is in the future.
* **Read tool.** A tool that changes no chain or dashboard state.
* **Approval.** A dashboard record of one write an agent asked for: its kind, its typed intent, its status, and, once signed, its transaction hash (§6.4).
* **Approval page.** `/approvals/{id}` on the dashboard, where the owner reviews, signs and submits an approval in their own session.
* **Delegated grant.** A row of `agent_connection_grants` (`migrations/0103_store_use_half.sql:1-10`) that lets one connection use the owner's hire of one listing through the Store caller, inside limits the owner set.
* **Classification table.** The table in `core cli/src/mcp_manifest.rs` that classifies every CLI command and lists each tool's arguments (§6.7.1).
* **Tool manifest.** The JSON file the CLI generates from the classification table and its clap command tree (§6.7.2).
* **Display unit.** US dollars when the network posts a CBY rate or is Cowboy Cloud; CBY otherwise (§6.3).

## 6. Specification

### 6.1 Endpoints

The server keeps its two addresses and their behavior (`routes/mcp.ts:84-134`):

| Path | Auth | Tools |
| - | - | - |
| `POST /api/mcp`, or `POST /mcp` on `MCP_PUBLIC_URL` | Bearer `cst_` or OAuth `csa_` token, required | Every tool the connection's scopes allow |
| `POST /api/mcp/public`, or `POST /public` on `MCP_PUBLIC_URL` | None; a token sent is ignored | `search_store`, `get_listing` |

The server MUST register only the tools a connection's scopes allow (§6.6), so `tools/list` never offers a tool that would refuse. Each request builds its own server and transport, as today (`routes/mcp.ts:59-82`). An unknown, revoked or expired token MUST get `401` with the RFC 9728 challenge, never a quiet downgrade to the public tools (`routes/mcp.ts:96-103`). An owner-made `cst_` token is good at both addresses; an OAuth token only at the address it was issued for (RFC 8707, `routes/mcp.ts:184-194`).

### 6.2 Catalog

Every CLI command is classified below. **Included** commands are tools. **Excluded** commands are not, for one of these reasons:

* **K. Local keys and configuration.** Creates, imports, exports or uses a key or a setting on the machine. The MCP server holds no owner key.
* **D. Local development.** Acts on a project directory, a local build or a simulator. The MCP server has no project directory.
* **O. Operator role.** Needs an operator, validator, system-deployer or governance role, or registers infrastructure (runners, relays, proxies, images, services).
* **R. Raw signing.** Signs, inspects for signing or submits caller-supplied transaction bytes, which would bypass the approval page's decoding.
* **A. Account authority.** Changes who may sign for the account, recover it or own an actor.
* **E. Explorer data.** Reads chain data that is not the owner's own, or that the read tools already cover. The explorer serves it.
* **F. Deferred.** A user action that joins this surface when its approval card exists (§9).

#### Included

| CLI command | MCP tool | Kind | Scope |
| - | - | - | - |
| `account balance`, `account info`, `wallet balance` | `get_balance` | read | `read` |
| `actor inspect` | `get_actor` | read | `read` |
| `job get`, `job status`, `job results` | `get_job` | read | `read` |
| `transaction get`, `transaction status` | `get_transaction` | read | `read` |
| `actor fund` | `prepare_fund_actor` | approval | `prepare` |

These tools have no single CLI command, and their classification-table entries carry `cli: null` with a hand-written schema (§6.7.1). The Store's tools take the Store's own arguments (a listing id, a price term, a monthly limit), not the CLI's, so they are written here too:

| MCP tool | Kind | Scope | What it lists or does |
| - | - | - | - |
| `search_store`, `get_listing` | read | public | The live Store catalog |
| `list_my_hires` | read | `read` | The owner's hires |
| `request_hire` | approval | `prepare` | Asks the owner to hire a listing, approved on the listing's hire flow (§6.4.2) |
| `list_actors` | read | `read` | The dashboard's index of actors the owner deployed; rows as `get_actor` |
| `list_jobs` | read | `read` | The index of jobs the owner's wallet submitted; rows as `get_job` |
| `list_transactions` | read | `read` | The index of transactions the owner's wallet sent or received |
| `list_rooms` | read | `read` | The owner's rooms in the dashboard |
| `get_request`, `withdraw_request` | read, write | `prepare` | A `request_hire` request |
| `get_approval`, `cancel_approval` | read, write | `prepare` | An approval (§6.4.4) |
| `read_feed` | read | `use_hire` | A feed the owner granted |
| `use_hire` | delegated grant | `use_hire` | A tool the owner granted (§6.5) |

#### Excluded

Subcommands of `account`, `actor`, `job`, `transaction`, `store`, `wallet` and `volume`:

| CLI command | Reason |
| - | - |
| `account nonce` | E. A signing detail; the approval page reads it. |
| `account auth`, `account set-policy`, `account set-recovery`, `account initiate-recovery`, `account cancel-recovery`, `account complete-recovery` | A. |
| `actor state`, `actor timers`, `actor jobs`, `actor logs`, `actor messages`, `actor code`, `actor pins`, `actor interface`, `actor address` | E. `get_actor` and `list_jobs` cover the owner's own; the rest is explorer data. |
| `actor transfer-owner` | A. |
| `actor call` | F. An arbitrary handler call has no decoded approval card. |
| `actor owner-funding`, `actor auto-topup show`, `actor auto-topup set` | F. Standing spends (§4). |
| `actor upgrade`, `actor update-offchain`, `actor publish-site`, `actor manifest-encode`, `actor lower` | D. |
| `job runners`, `job verified` | E. |
| `job submit` | F. A job spends under runner and model parameters the approval card does not render. |
| `transaction submit`, `transaction sign`, `transaction inspect` | R. |
| `store use`, `store list`, `store current` | K. Store selection in the local environment. |
| `store hire` | K. Signs the hire with the local key; `request_hire` asks the owner instead. |
| `store search`, `store show`, `store hires`, `store hire-status`, `store get-*` | E. The Store's own tools cover the owner's reads. |
| `store deposit`, `store withdraw`, `store renew`, `store set-renewal` | F. Hire money actions with no decoded approval card. |
| `store sign-per-call-receipt` | R. |
| `store add`, `store remove`, `store submit`, `store submissions`, `store setup`, `store install`, `store status`, `store resume`, `store unpause`, and the Store protocol commands (`declare`, `declaration-id`, `version`, `retire`, `register-store`, `grant`, `revoke-grant`, `register-artifact`, `retire-artifact`, `pause`, `revoke`, `expire-hire`, `settle`, `attest`) | O or D. Creator, operator and installation commands; installations are run on Cowboy. |
| `wallet create`, `wallet address`, `wallet upgrade`, `wallet create-mnemonic`, `wallet import-mnemonic`, `wallet accounts`, `wallet export`, `wallet import-hex` | K. |
| `volume auto-top-up` | F. A standing spend (§4). |
| `volume withdraw`, `volume delete` | F. Owner money and data actions with no decoded approval card. |
| `volume list`, `volume ls`, `volume mount`, `volume cat`, `volume info`, `volume allow-actor` | D or F. File access through a local CBFS client, and an access grant with no approval card. |

Whole top-level commands:

| CLI command | Reason |
| - | - |
| `init`, `check`, `build`, `run`, `test`, `deploy`, `verify-deploy`, `lib`, `workload`, `deploy-code`, `cbfs`, `cbss-devnet-frame` | D. `deploy` builds from a project directory; a deploy approval is deferred with the other standing spends (§9). |
| `transfer` | F. Offered as `prepare_transfer` once its approval page decodes a `Transfer` (§6.4.2). |
| `topup` | F. A card payment through a CLI link starts from a code the terminal shows; an approval has no terminal (§9). |
| `env`, `login`, `logout`, `whoami`, `dashboard`, `billing`, `usage`, `console`, `completions`, `version` | K. Local credentials, Labs session commands and CLI configuration, or a local program. |
| `secrets` | K. A secret value never passes through an agent; the Store refuses secret-shaped text (`store-mcp-tools.ts:809-824`). |
| `runner`, `relay`, `proxy`, `container`, `tee`, `cluster`, `status`, `entitlement`, `timer`, `bridge` | O. |
| `cbqs` | O for `provider-register` and `provider-update`; F for `create-stream` and `close-stream`. |
| `cowchat` | O for `register-service` and `deregister-service`; E for `services`; F for `rooms create`. |
| `rooms` | F for every write: room setup is a CIP-48 batched plan with its own approval card (`frontend/src/components/agent/RoomSetupApprovalCard.tsx`). E for `inspect`, `trace` and `seat-id`; `list_rooms` covers the owner's rooms. |
| `watchtower` | O for the publisher commands (`init`, `new`, `register-feed`, `feed`, `derive`, `keygen`, `sign-result`); K for `use`; E for `list`, `feeds` and `watch`. A hired feed is read with `read_feed`. |
| `faucet`, `credit` | O. Network-funding doors with their own abuse controls. |
| `block` | E. |
| `session` | F. A payment session spends under parameters the approval card does not render. |
| `token`, `trading-post` | F for CIP-20 token transfers; `trading-post` is hidden and superseded by `store`. |

### 6.3 Amounts

Every amount a tool returns or accepts MUST follow the dashboard's display rule (`frontend/src/lib/cloud-deploy.ts:33-50`):

1. On Cowboy Cloud (`IS_CLOUD_DEPLOY=true`, `backend/src/config.ts:295`) amounts are US dollars at the posted rate `CBY_USD_PRICE`. A tool MUST NOT name CBY in its title, description, output or error text. With no posted rate, a tool that would return or accept an amount MUST return `not_available`.
2. On any other network with a posted rate, amounts are US dollars as on Cloud.
3. On a network with no posted rate, amounts are CBY decimal strings with up to 9 places (1 CBY = 10<sup>9</sup> base units).

An amount in output is an object `{ "usd": "12.34" }` or `{ "cby": "1.5" }`, never a bare number. A dollar figure MUST be computed from base units with integer arithmetic and rounded once, as `decimalCbyUsd` does (`cloud-deploy.ts:54-63`); a maximum rounds up. An amount input is `amount_usd` (a decimal string, at most 2 places) under rules 1 and 2 and `amount_cby` (at most 9 places) under rule 3; the server registers the one its network uses. A dollar input converts to base units once, when the tool is called, rounded down. `search_store`'s `max_price` and every Store price text follow the same rule.

Limits the owner sets on connections, grants and hire requests are dashboard ledger amounts, given in US dollars (`monthly_limit_usd`) and stored in US cents (`limit_minor`) on every network (`routes/agent-connections.ts:28-29`). They are not chain amounts and are not converted.

The posted rate is the one `GET /api/cli-links/capabilities` reports as `cbyUsdPriceMicro` (`backend/src/routes/cli-links.ts:325-332`).

### 6.4 Approvals

A write tool MUST NOT sign, submit or relay a transaction. It validates its arguments, checks them against the chain where it can (the target exists and is the owner's, the balance can cover it), records an approval, and returns:

```json theme={"system"}
{
  "approval_id": "3f0c…",
  "status": "waiting",
  "approval_link": "https://<dashboard>/approvals/3f0c…",
  "summary": "Add $25.00 to actor 0x9a4b…77e1",
  "expires_at": "2026-11-05T18:30:00Z"
}
```

The server writes `summary` from the validated intent. An agent cannot supply it.

#### 6.4.1 Record

`mcp_approvals` holds:

| Column | Meaning |
| - | - |
| `id` | UUID; the approval page's path. |
| `connection_id`, `account_id`, `wallet` | The connection that asked and its owner, copied at creation. |
| `kind` | One of the kinds of §6.4.2. |
| `intent` | The kind's arguments after validation, as JSON. Every amount is in base units, fixed when the approval is made. |
| `quote` | What the server read when it was asked: the posted rate and the maximum fee then. Advice for the agent; never compared or signed. |
| `nonce_floor` | The owner's account nonce when the approval was made, read from the node. |
| `confirmed` | The intent as the owner confirmed it on the page; set when the page reports a signing hash. |
| `tx_nonce` | The signed transaction's nonce, decoded by the `submitted` route. |
| `status` | §6.4.4. |
| `tx_hash` | The signed transaction's hash. Unique across `mcp_approvals`. |
| `expires_at` | 30 minutes after creation, the CLI-link approval window (`backend/src/services/cli-links.ts:22-23`). |

A tool MUST return the existing approval, not a new one, when the same connection asks again for the same kind and intent while one is `waiting` and unexpired. A connection MUST NOT have more than 5 approvals `waiting` and unexpired, nor create more than 10 in a day; `request_hire` requests keep their own caps (`store-mcp-tools.ts:171`) and do not count toward these. When the owner declines a connection's third approval in a row, the same write MUST set the connection's `may_prepare` to false, so its approval tools are no longer registered until the owner turns `prepare` on again in Connected apps.

#### 6.4.2 Kinds

| Kind | Intent | What the page signs or pays | Prepare route |
| - | - | - | - |
| `fund_actor` | `actor`, `amount` | One `FundActor` from the owner's wallet | `POST /api/actors/{address}/funding/prepare` (`backend/src/routes/actor-balance.ts:11-33`) |
| `transfer` | `to`, `amount` | One `Transfer` | `POST /api/transfers/prepare`, not built yet |

`fund_actor` MUST name an actor whose deployer, in the dashboard's index, is the owner's wallet; the tool and the `submitted` route both check. `transfer` MAY name any account; the page shows the full recipient address and whether the owner's wallet has sent to it before.

A kind is offered only once its page decodes and verifies its transaction (§6.4.3 step 5).

`request_hire` keeps its own record (`store_requests`, `migrations/0101_store_mcp.sql:14-31`), its seven-day lifetime (`store-mcp-tools.ts:166`) and its page, `/requests/{id}`, where the owner approves by hiring as usual (`store-mcp-tools.ts:622-625`). It follows §6.4's rules otherwise.

#### 6.4.3 Approval page

The approval page MUST run in the owner's own session and MUST:

1. Refuse an approval of another account with `403`, as `/api/store/requests/{id}` does (`routes/agent-connections.ts:269-276`).
2. Refuse an approval that is not `waiting`, or whose connection is not live.
3. Name the connection that asked, by the name the owner saw at connect time.
4. Build the transaction from the approval's intent through the kind's prepare route, in the owner's session. Building at approval time keeps the nonce and fees current.
5. Decode the prepared bytes in the browser with the shared WASM inspection (`frontend/src/lib/agent/client-signing.ts:12`) and refuse to sign when any decoded fact differs from the confirmed intent: instruction kind, sender, recipient or actor, and amount. A mismatch refuses; it does not warn and continue.
6. Show the decoded facts as the transaction's content, with every address in full. A name the server looked up (an actor's name) is shown beside its address, never in place of it.
7. Sign in the owner's wallet, prompting the owner. The page MUST NOT sign inside the dashboard's signing window (`frontend/src/lib/wallet/signing-window.ts:1-15`), since an agent's request is not something the owner started.
8. Before broadcasting, send the unsigned transaction bytes and the confirmed intent to `POST /api/approvals/{id}/submitted`, in the owner's session. The page MUST NOT broadcast unless that route accepted them. Between that report and broadcast only the 65-byte signature slot may change; the transaction's hash is its identity with signatures zeroed (CIP-40 §7.1, §7.3), so the route knows it before the signature exists.

The owner MAY change the amount on the page. The confirmed intent then differs from the agent's, the page says so, and `get_approval` reports the confirmed amount.

`POST /api/approvals/{id}/submitted` MUST check that the approval is the session's account's, is `waiting` and unexpired, and that its connection is live. It MUST decode the bytes itself and check that the sender is the approval's wallet, the nonce is at or above `nonce_floor`, the decoded content equals the confirmed intent, the confirmed intent differs from the intent in nothing but the amount, and no other approval holds the hash. It then sets `submitted`, `tx_hash`, `tx_nonce` and `confirmed`. The server MUST settle from the chain only: a `submitted` approval becomes `done` when the hash's receipt succeeds, and `failed` when the receipt fails or the account's nonce passes `tx_nonce` with no receipt for the hash, which also covers a page that closed before broadcasting. Nothing the page reports after the route accepted changes the outcome.

#### 6.4.4 Status

| From | To | Who | When |
| - | - | - | - |
| — | `waiting` | agent | A prepare tool is called. |
| `waiting` | `submitted` | owner | The page reports a signing hash (§6.4.3 step 8). |
| `waiting` | `declined` | owner | `POST /api/approvals/{id}/decline`, or Decline all on the page. |
| `waiting` | `cancelled` | agent or owner | `cancel_approval`, or the connection is revoked (§6.6.2). |
| `waiting` | `expired` | server | Read after `expires_at`. |
| `submitted` | `done`, `failed` | server | Read after the receipt or the nonce settles it (§6.4.3). |

The server settles an approval when it is read, as `settleRequest` does for hires (`store-mcp-tools.ts:593-620`), so nothing hooks into the signing flow. A `submitted` approval never expires: its transaction may still land. `get_approval { approval_id }` returns the status, the confirmed amount and, once `submitted`, the transaction hash. `get_approval` and `cancel_approval` act only on approvals of the calling connection.

The owner gets one notice per approval, deduplicated on its id, as `request_hire` sends (`store-mcp-tools.ts:396-406`). The notice names the connection and the action, with no amount. The approval page lists every other `waiting` approval from the same connection.

### 6.5 Delegated grants

`use_hire` is the one tool that spends without a per-call approval. It stays as built (`store-mcp-tools.ts:454-554`):

* The owner grants one connection the use of their hire of one listing, with a monthly limit, behind step-up (`routes/agent-connections.ts:1-7`).
* The Store caller signs the call. The hire accepts it only because the owner named that caller on the hire with `allow_caller` (CIP-33; `backend/src/services/store-use-dispatcher.ts:6-8`). The Store caller's key is the dashboard's, never the owner's (`STORE_CALLER_PRIVATE_KEY`).
* The most a use can cost is reserved against the hire's limit, the grant's limit and the connection's monthly limit before the call, and settled or released after (`store-mcp-tools.ts:470-541`).
* The grant is re-checked before every signed call and before the result is returned (`store-mcp-tools.ts:510`, `:543-546`).

No other tool MAY use the Store caller's key or any other dashboard-held key to act for an owner.

### 6.6 Authorization

#### 6.6.1 Scopes

A connection holds any of three scopes:

| Scope | Tools | Stored as |
| - | - | - |
| `read` | Every read tool except the public two and `read_feed` | `agent_connections.may_read` |
| `prepare` | Every approval tool, `request_hire`, `get_request`, `withdraw_request`, `get_approval`, `cancel_approval` | `agent_connections.may_prepare` |
| `use_hire` | `use_hire`, `read_feed` | One or more `agent_connection_grants` rows |

`may_prepare` replaces `may_request` (`migrations/0101_store_mcp.sql:7`): the column is renamed and every reader moves to it. `may_add_free_skills` (`migrations/0102_store_mcp_oauth.sql:37`) is part of `prepare`: an owner who gives no `prepare` gives no free-skill additions either. `may_read` and `may_prepare` MUST default to false and MUST be set only by an explicit `true` from the consent form or the Connected apps form (`frontend/src/components/connected-apps/GrantForm.tsx:44-46`); a form or client that leaves one out grants nothing.

The OAuth server advertises `scopes_supported: ["read", "prepare", "use_hire"]` in its RFC 8414 and RFC 9728 metadata and in the `WWW-Authenticate` challenge, in place of the single scope `store` (`services/oauth.ts:85`, `routes/mcp.ts:129`, `:171`). A client MAY request any subset in `scope`. The consent page shows one choice per scope, all unchecked; the owner's choices decide what is granted, never the request. `oauth_codes` carries `may_read` and `may_prepare` beside its `grants` (`migrations/0103_store_use_half.sql:26`). The token response's `scope` is the scopes the connection holds, space-separated (`services/oauth.ts:518` returns `store` today). A refresh reports them again and never widens them; a wider grant is a new consent.

The server MUST also check the scope inside each tool, so a registration slip fails closed with `not_allowed`.

#### 6.6.2 Revocation

Revoking a connection (`routes/agent-connections.ts:323-335`) MUST in the same database transaction:

* end its tokens, as today, since every token lookup joins the live connection (`routes/mcp.ts:183-194`);
* set its `waiting` approvals to `cancelled`;
* leave its `submitted` approvals as they are, since their transactions may still land.

Grants end with the connection, and `use_hire` re-checks the grant before each signed call (§6.5). A connection whose `expires_at` passes is no longer live; nothing runs at that moment, so the page and the `submitted` route check liveness themselves (§6.4.3). A transaction the owner signed before revocation stands: the owner's signature, not the connection, authorized it.

### 6.7 Tool manifest

#### 6.7.1 Classification table

`core cli/src/mcp_manifest.rs` holds one entry for every top-level command and for every subcommand of a command that has any included subcommand. An entry is one of:

* `Exclude { reason }`, with a reason code from §6.2.
* `Include { tool, kind, scope, description, args, omit }`, where `description` is the tool's text for an agent (the first command's clap about when empty), `args` lists, for each argument the tool takes, the clap argument it comes from, its role (`plain`; `amount`, which becomes the amount pair of §6.3; or `owner`, supplied by the connection and never in the schema) and its text for an agent (the clap help when empty), and `omit` lists the command's other arguments, which the tool does not take.
* `Group`, for a command whose subcommands have entries of their own.
* `Tool { name, kind, scope, description, properties }`, for a tool with no CLI command (`cli: null`), with its schema written in the table.

Several CLI commands MAY map to one tool, as `account balance`, `account info` and `wallet balance` map to `get_balance`; the tool's arguments are the union of what its entries name, and each named argument MUST have the same type in each command.

A test walks `Cli::command()` and fails when:

* a command has no entry, or an entry names a command clap does not have;
* an included command has an argument in neither `args` nor `omit`, so adding a flag to an included command needs a decision;
* an `Include` names an argument whose value parser reads a path, a URL or a key (`--key-file`, `--rpc-url`, `--private-key` and their kind).

#### 6.7.2 Generation

`cowboy mcp-manifest`, a hidden command, writes the manifest:

```json theme={"system"}
{
  "schema": "cowboy-mcp-manifest/v1",
  "cli_version": "0.0.53",
  "tools": [
    {
      "name": "get_job",
      "cli": [["job", "get"], ["job", "status"], ["job", "results"]],
      "kind": "read",
      "scope": "read",
      "description": "<the first command's clap about>",
      "input_schema": { "type": "object", "properties": { "job_id": { "type": "string", "description": "<clap help>" } }, "required": ["job_id"], "additionalProperties": false }
    }
  ],
  "excluded": [{ "cli": ["wallet", "export"], "reason": "K" }]
}
```

For an `Include`, each `plain` argument becomes a property: its long name in snake case, its value parser as the JSON type (integer amounts and identifiers as decimal or hex strings), `required` from clap, its help text as the description and `possible_values` as an `enum`. An `amount` argument becomes `amount_usd` and `amount_cby`, each with a description the generator writes from §6.3, never the clap help, which names CBY. A test MUST fail when any description in the manifest outside an `amount_cby` property names CBY.

`excluded` lists every command that is not a tool with its §6.2 reason code, so the catalog of §6.2 is machine-readable. The manifest contains no network-specific values. It is generated at a CLI version on core's devnet branch and committed to the dashboard as `backend/src/mcp/cli-manifest.json`.

#### 6.7.3 Registration

The dashboard registers each tool's name, description and argument descriptions from the manifest; a handler supplies the title, its arguments' validators (lengths and ranges) and the behavior. The manifest's `scope` is informational: the dashboard's scope gating (§6.6.1) decides what a connection is offered. On a network whose amounts read in dollars the server registers `amount_usd` and drops `amount_cby`, and the reverse under rule 3. A test MUST fail when the manifest names a tool with no handler, when a handler has no manifest entry, or when a handler's argument set differs from the manifest's. A test runs the dashboard's vendored CLI's `cowboy mcp-manifest` and fails on any difference from the committed file, so the committed file is the CLI's output; it skips while the vendored CLI predates the command.

### 6.8 Errors

Tool errors keep the Store's shape: `isError: true`, `structuredContent: { code, message, ...extra }`, and the code repeated in the text (`routes/mcp.ts:241-257`). The codes are the existing `ToolErrorCode` set (`store-mcp-tools.ts:52-62`) plus `insufficient_balance`. A read that cannot reach the chain or the index MUST return `not_available` with `retry_after`; it MUST NOT return an empty result in place of a failed read. A get tool for an object the owner does not own MUST answer `not_found`, as for one that does not exist.

Every string argument of every tool MUST be secret-scanned before it is stored or logged (`store-mcp-tools.ts:809-824`), with the existing exemption for listing ids.

### 6.9 Parameters

| Parameter | Value |
| - | - |
| Approval lifetime while waiting | 30 minutes |
| Approvals waiting per connection | 5 |
| Approvals created per connection per day | 10 |
| Declines in a row before `prepare` pauses | 3 |
| List page size, default and most | 20 and 100 |
| Job result returned per runner | 8,000 JSON characters, then cut with `result_truncated` |
| Calls per minute, connected and anonymous | 120 and 60 (`routes/mcp.ts:44-45`) |

None is consensus state; each is a dashboard constant.

## 7. Rollout

The sign-in address answers only where Connected apps is on: `SHOW_CONNECTED_APPS=true` (`backend/src/config.ts:224`), checked on every request (`routes/mcp.ts:95`). Off, it returns `404`, and no tool of this CIP is reachable. The public address serves only the two catalog reads and does not depend on the flag (`routes/mcp.ts:107-109`). Cowboy Cloud has Connected apps off. Canyon has it on for the `use_hire` test, through `show_connected_apps` in its `aws-infrastructure` environment.

Cloud turns on the same way canyon did: one change to the Cloud environment in `aws-infrastructure` sets `show_connected_apps = true` for the Cloud dashboard. That change ships after:

1. The read tools, the approval tools and the tool manifest are on the dashboard's main branch and have run on canyon.
2. Every tool's output on canyon has been checked against §6.3 with `IS_CLOUD_DEPLOY=true`.
3. The operator decides the moment. Nothing in this CIP turns Cloud on.

`STORE_CALLER_PRIVATE_KEY` is separate. Without it `use_hire` is not offered (`routes/mcp.ts:366-387`); Cloud can have Connected apps on with no Store caller.

## 8. Security Considerations

### 8.1 Blind signing

The owner's browser signs only bytes it decoded itself, and every fact the approval page shows as the transaction's content comes from that decoding (`client-signing.ts:12`). The server-recorded `quote` is advice to the agent. The guarantee is as strong as the page that runs the decoder: the WASM inspection and the page are served by the dashboard, so a compromised dashboard can still lie to the owner. What this design rules out is an agent, or a server bug in the MCP path, steering what the owner signs.

### 8.2 The agent is untrusted

The agent chooses every argument. The server scopes every read and write by the connection, never by an argument. An agent cannot make an approval for another account, read or cancel another connection's approval, or read a listing's setup answers. Third parties write some of what the read tools return (actor names, job results, room names); a read tool's description MUST say its output is data, not instructions, because a prompt injection planted there can steer the agent's next request.

### 8.3 Steered recipients

An agent steered by injected text can ask to pay an attacker. Decoding proves the server did not swap the recipient, not that the owner meant it. `fund_actor` therefore accepts only the owner's own actors. `transfer` shows the full recipient address as its primary fact, says whether the owner's wallet has paid it before, and counts against the connection's approval caps (§6.9).

### 8.4 Approval phishing

An approval link is a request, never authority. Opening one does nothing; the owner must be signed in to the approving account, see the decoded transaction and sign it. A link to another account's approval shows only that it is for another account. Approval pages carry the connection's name as the owner saw it at consent; a client name that imitates Cowboy or another product is refused at registration (`services/oauth.ts:228`).

### 8.5 Approval fatigue

An agent that asks for many approvals trains the owner to sign without reading. The caps of §6.9, one notice per approval, the one-waiting-approval-per-intent rule and the pause after three declines bound it, and Decline all ends a burst in one action.

### 8.6 Reporting a hash

The `submitted` route takes only a hash and the owner's confirmed intent, in the owner's session, which an agent does not have (it is not on the open-CORS list, `routes/mcp.ts:149-157`). A hash cannot settle an approval by itself: settlement reads the chain and requires the transaction's sender, its decoded content and a nonce at or above `nonce_floor`, so an older matching transaction cannot mark a new approval done, and one transaction cannot settle two approvals.

### 8.7 Reads disclose

`read` shows an agent the owner's balance, actors, jobs, rooms and transaction history. It is a separate choice at consent and is off unless the owner turns it on.

### 8.8 Delegated spend

`use_hire` is the only standing spend this CIP permits. Its bound is the smallest of the hire's limit, the grant's limit and the connection's monthly limit; the reservation is taken before the call, and an unreadable limit refuses rather than spends (`store-mcp-tools.ts:469-474`).

### 8.9 Manifest creep

The classification table admits arguments one by one and refuses path, URL and key arguments (§6.7.1), so a flag added to an included CLI command reaches no agent until someone decides it should.

## 9. Future Work

* Approval kinds for `deploy`, `actor owner-funding`, `actor auto-topup set` and `volume auto-top-up`. Each creates a standing draw on the owner's balance, so each needs a decoded cap on its approval card, a cap the owner must set, and a place in Connected apps that lists what an agent's approvals left switched on.
* A `top_up` approval: a card payment through the CLI-link money flow, bound to an approval in place of the terminal's code, with the amount from the server's checkout record and the owner's step-up.
* Approval kinds for `actor call`, `job submit`, `session`, CIP-20 token transfers and CIP-48 room setup, each when its decoded approval card exists.
* Batching several waiting approvals from one connection into one CIP-48 transaction with one signature.

## 10. Reference Implementation

* Dashboard: `backend/src/routes/mcp.ts` (tool registration), `backend/src/services/mcp-user-tools.ts` (read tools), `backend/src/services/mcp-amounts.ts` (§6.3), `backend/src/services/mcp-approvals.ts` (approvals), `frontend/src/app/approvals/[id]/page.tsx` (approval page), `backend/src/mcp/cli-manifest.json` (pinned manifest).
* Core: `cli/src/mcp_manifest.rs` (classification table and generation). No consensus code changes.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.