Skip to main content
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)
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): 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

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:

Excluded

Subcommands of account, actor, job, transaction, store, wallet and volume: Whole top-level commands:

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 = 109 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:
The server writes summary from the validated intent. An agent cannot supply it.

6.4.1 Record

mcp_approvals holds: 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

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

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

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.