Status: Draft
Type: Standards Track
Category: Core
Created: 2026-04-28
Updated: 2026-10-03
Requires: CIP-14 v2 (DNS-Addressable Actors), CIP-15 v2 (Public Asset Hosting and HTTP Routing), CIP-18 (Payments — §12 normatively defers to CIP-18 §13 for payment wire format and
_meta field semantics)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.
Revision history
- 2026-10-03 — Clarify sender-paid Gateway gas, sponsorship budgets and the decided actor-funded timer rule (§12.1).
- r2 (2026-05-11) — CIP-18 elevated from Companions to Requires. §12 (Authentication and Payment) normatively defers to CIP-18 §13 for the MCP JSON-RPC payment wire format,
_meta.payment-authorizationcarrier, and-32402error mapping; without CIP-18, §12 has no implementable definition. The current CIP-18 header retains CIP-19 as a native-interface dependency for §13 MCP gating.- r1 (2026-04-28) — Initial draft.
Payment release contract: HTTP and MCP MUST share CIP-18 purchase identity, confirmation-before-dispatch and authenticated saved-result recovery. 202 is an acknowledgement, not completion. Unknown execution MUST NOT trigger another paid invocation. Actor-funded MCP retries are bound to the original server-issued session; a purchase ID alone is not result-access authorization. Paid 101 upgrades and resumable SSE remain outside this release. See CIP-18 recovery.
1. Abstract
Background
MCP clients need a tool list and a way to invoke actor handlers.Goal
This CIP specifies how the Gateway exposes CIP-14 actors as Model Context Protocol servers. Theingress.mcp entitlement enables this behavior. The Gateway:
- Hosts an MCP server at
https://<0xactor>.canyon.cowboylabs.net/_cowboy/mcpusing MCP’s streamable HTTP transport (spec version2025-11-25). - Generates
tools/listfrom the actor’s CIP-15 routes table. Every Method-target route becomes one MCP tool. - Translates
tools/callinvocations into the same actor dispatch (query path or command path) that the equivalent HTTP request would have used. Actor handlers are unchanged; they do not know whether the invocation arrived as HTTP or MCP. - Applies CIP-18 payment gating over MCP’s JSON-RPC transport extension. Payment challenges use JSON-RPC error code
-32402; credentials and receipts use the MCP_metafield.
- MCP resources and prompts. v1 is tools-only.
- SSE-style streaming of tool results, which a follow-on CIP will specify.
- Custom tool name remapping. Tool names are derived mechanically from route method names.
- Server-initiated notifications and sampling.
2. Motivation
CIP-14 made Cowboy actors HTTP-addressable. CIP-15 added verb-aware routing and per-route payment policy. Together they let agents call actor handlers as a familiar REST API. MCP clients discover and invoke tools without a separate SDK for each server. An HTTP client needs the API contract. Actors provide the following through MCP:- An agent can audit an actor tool’s on-chain, deterministic code before calling it.
- CIP-18 allows an MCP tool to require payment before invocation through the JSON-RPC payment transport.
- An actor with
ingress.httpandingress.mcpexposes a payable MCP server at<0xactor>.canyon.cowboylabs.net/_cowboy/mcpwithout a separate hosting provider or API key issuance. - The Gateway derives the CIP-18 OpenAPI document and MCP
tools/listfrom the routes table. Agents can use either to discover actor endpoints.
3. Design Goals
- Expose the author’s routes (CIP-15) as MCP tools without changing handler code.
- Derive the tool list and the CIP-18 OpenAPI document from the same routes table.
- Dispatch
tools/callthrough CIP-14’s existing query and command paths. - Implement payment via CIP-18. MCP gating reuses CIP-18 wire formats and its existing payment code path over MPP’s JSON-RPC transport.
- Terminate MCP at the Gateway, with runners providing private compute as in CIP-14.
- Support unmodified MCP
2025-11-25over streamable HTTP for any conformant client.
4. Non-goals
- MCP resources and prompts are out of scope; v1 supports tools only. CIP-15 volumes could plausibly back resources in a future revision.
- SSE and chunked tool results are deferred; v1 returns one response per call.
- v1 does not implement server-initiated requests. MCP lets servers send
sampling/createMessageandnotifications/*to clients. - This CIP does not customize tool names. Tool names are derived from the CIP-15 route’s
target.name. A future CIP may add an explicitmcp_nameoverride. - MCP authentication outside CIP-18 is out of scope, including OAuth, API keys, and other MCP auth modes. Payment is the only gating mechanism in v1.
- An actor-side MCP client is out of scope. This CIP is about actors as MCP servers. Actor consumption of external MCP servers (the existing
runner-mcpcrate) is unrelated.
5. Definitions
- MCP is the Model Context Protocol, version
2025-11-25(the spec dated 2025-11-25 on modelcontextprotocol.io). It uses JSON-RPC 2.0 framing. - Streamable HTTP is MCP’s HTTP-based transport mode (replaces the older HTTP+SSE transport from earlier MCP revisions).
- A tool is an MCP-discoverable, callable function with a JSON-Schema-described input and a structured output. In Cowboy, a tool corresponds 1:1 with a Method-target route from CIP-15.
- The Gateway derives the tool name from
route.target.nameper §10. - The MCP
_metafield is reserved for protocol extensions. CIP-18 uses it to carry payment credentials and receipts.
6. Architecture
7. The ingress.mcp Entitlement
The actor MUST also hold
ingress.http (CIP-14). MCP exposure without HTTP ingress is undefined.
Under CIP-18, if the actor also holds payment.gate, MCP tool calls inherit the route’s pays policy from CIP-15. pays = "actor" routes are free over MCP. pays = "caller" routes require payment via §11 below.
8. MCP Endpoint
The Gateway exposes:2025-11-25 over the streamable HTTP transport. It accepts both POST (for JSON-RPC requests from clients to servers) and GET (for the optional SSE stream from server to client that the streamable HTTP transport defines). v1 does not emit server-initiated notifications, so the SSE stream is open-but-empty.
A request to any other method on /_cowboy/mcp returns 405 Method Not Allowed.
The endpoint is reserved per CIP-18 §17 (CIP-14 §8.6 reserves the /_cowboy/* prefix generally; the mcp sub-path itself is declared by CIP-18 §17). It is intercepted by the Gateway before route resolution; the routes table is not consulted to dispatch the MCP endpoint itself.
8.1 Session lifecycle
The streamable HTTP transport assigns aMcp-Session-Id header on the initial initialize response. Subsequent requests in the same session MUST include this header. Sessions are terminated by an explicit DELETE to /_cowboy/mcp or by inactivity beyond MCP_SESSION_IDLE_TIMEOUT_SECONDS.
Session state held by the Gateway is limited to:
- The negotiated
protocolVersion(always2025-11-25in v1). - The client’s
clientInfo. - The cached routes-table version observed at session start (for consistent
tools/list).
9. Capability Negotiation (initialize)
The Gateway responds to initialize with:
capabilities.tools.listChanged: false reflects that v1 does not emit server-initiated notifications (§4, §8). The SSE stream stays open without sending events. Clients that need a fresh tool list MUST re-query tools/list periodically. Server-initiated notifications/tools/list_changed is deferred to a follow-on CIP.
resources and prompts capabilities are NOT advertised in v1.
completions and sampling are NOT advertised. Cowboy actors do not initiate model calls back to the client.
10. tools/list
The tool list is generated from the actor’s CIP-15 routes table. Generation is deterministic and verifiable.
10.1 Generation algorithm
- Read the routes table at
__cowboy/routesfrom the actor’s KV state (using the CIP-15 §8.12 Gateway-to-full-node fetch protocol). - Filter to routes where:
target.kind == "method"(Volume targets are not tools)enabled == truetarget.nameis not iningress.mcp.exclude_routes
- Group routes by
target.name. Each unique method name produces one tool. - For each group, validate that all routes share a compatible input schema (§10.3). If not, the group is skipped and a warning is logged in the Gateway’s structured-error output.
- Emit one
Toolentry per group.
10.2 Tool entry shape
_meta.cowboy block is non-normative metadata that lets MCP-aware Cowboy clients introspect routing details without re-fetching the OpenAPI doc.
10.3 Input schema derivation
For each tool, the Gateway constructs the JSON Schema from:- Path parameters from
route.path(CIP-15 §6.3). Each{param}becomes a required string property. - Query parameters and body from the actor’s OpenAPI document (CIP-18 §14). Path-Item schemas under the matching verb supply property types and descriptions.
- If no schema is declared, fall back to a permissive
additionalProperties: trueobject.
GET /users/{id} and HEAD /users/{id} both target users.get), the Gateway requires that path parameters and bodies are identical. If they differ, the routes are considered incompatible and the tool is skipped (§10.1 step 4).
10.4 Tool name mapping
The MCP tool name is:sanitize replaces any character outside [a-zA-Z0-9_] with _. CIP-15 method names typically use dotted notation (e.g., users.get); after sanitization this becomes users_get.
Names beginning with _cowboy are reserved for system tools (§14). If tool_name_prefix + sanitize(...) would collide with a reserved name, the route is skipped.
11. tools/call (Dispatch Contract)
A tools/call request maps onto the same actor dispatch as the equivalent HTTP request.
11.1 Request shape
11.2 Translation to HTTP equivalent
The Gateway:- Looks up the route group for
params.name(reverse of §10.1). - Picks the canonical route in the group (highest priority; ties broken by storage order).
- Substitutes path parameters from
argumentsintoroute.path. - Splits remaining arguments into query parameters and body per the OpenAPI schema for the selected verb.
- Constructs a synthetic
HttpRequestEnvelope(CIP-14 §8.1) with:verb=route.verb. A route withverb == "ANY"is dispatched asPOST(defaulting to the unsafe/command path when routemodeis absent, §11.3): atools/callcannot signal HTTP safety, soANYdefaults conservatively to state-mutating. Without an explicit routemode, actors wanting a safe (query-path, no-consensus, cheaper) MCP tool MUST register the route with an explicit safe verb (GET/HEAD) rather thanANY. An explicitmodeselects the dispatch path independently of the normalized verb.path= the substituted pathquery= serialized query parametersbody= serialized body (JSON, unless OpenAPI declares otherwise)headers= a synthesized minimal set (content-type,accept, plusX-Cowboy-Mcp-Session-Id)path_params= the matched named parameters
11.3 Dispatch
The Gateway resolves the routemode before dispatching the envelope per CIP-14 §8. An explicit mode overrides the verb (CIP-15 §6.2); otherwise GET/HEAD default to Read and other verbs default to Submit. Gas follows the resolved mode:
- The
Readmode uses the unsigned CIP-14 query path viaread_handler. No transaction, consensus or transaction gas. - For
Submit/SubmitNoWait, the Gateway signs and pays transaction gas from its wallet, including when an explicit mode selects this path for GET/HEAD. The required registry-mediated command path isGatewayRegistry.dispatch(); CIP-14 §8.4.1 distinguishes that contract from the directExecuteActorpath.
11.4 Response shape
The actor handler returns anHttpResponseEnvelope (CIP-14 §8.2). The Gateway maps it to MCP:
- For
content-type: application/json, emit a singletextcontent block with the JSON and a siblingstructuredContentfield carrying the parsed JSON (per MCP2025-11-25). - For
content-type: text/*, emit a singletextcontent block. - For binary types (
image/*,application/octet-stream), emit oneimageorresourcecontent block per MCP’s content-type rules. Bodies exceedingMAX_TOOL_OUTPUT_BYTESare truncated and the response is markedisError: truewith atruncatedflag in_meta.cowboy.
11.5 Error mapping
- For HTTP 4xx other than 402, set
result.isError = trueand describe the error in the content. Send no JSON-RPC error frame. - For HTTP 5xx, send a JSON-RPC error frame with
code = -32603(internal error),message = "Actor handler failed",datacarrying the response body if size-bounded. - Handle HTTP 402 per §12.
- For a network error or timeout, send a JSON-RPC error frame with
code = -32000,message = "Gateway dispatch failed".
12. Authentication and Payment
This section defers to CIP-18 §13 for the wire format. CIP-19 specifies only how it integrates with the dispatch contract.12.1 No payment required
Routes withpays = "actor" (CIP-15 default) charge the caller no service price when no enabled CIP-18 price_table overrides that default. The Gateway dispatches by the resolved mode (§11.3): GET/HEAD default to unsigned Read with no transaction gas, but an explicit mode overrides the verb. Submit and SubmitNoWait calls are signed by the Gateway, which pays their gas from its own wallet under CIP-14 §8.4.3. The actor’s hot balance is not debited for the Gateway-signed top-level transaction; deferred work the handler emits is billed to the emitting actor, then its FallbackToOwnerBalance owner for any shortfall, at basefee with zero tip (CIP-28 §3.4). The Gateway enforces a per-actor budget alongside the Gateway’s per-transaction cap, counting actual committed gas plus unresolved signed maxima. Unresolved evidence keeps the maximum while retryable lookups remain queued; later valid evidence settles the actual charge. A definitive miss (strict not-found for all signed variants), malformed or mismatched evidence, or queue overflow keeps its maximum for the process lifetime. Evidence retry and exhaustion rules follow CIP-14 §8.4.3. A callee cannot bill the Gateway for timers: CIP-5 §4.2 requires an actor to pay for its own timers (the canonical Watchtower Feed’s owner-paid start/restart applies only to the Feed owner’s own signed call). There is no callee-scheduled, sender-billed timer path to exclude from the Gateway budgets under this rule (CIP-14 §8.4.3).
12.2 Payment required, no credential
Routes withpays = "caller" and no _meta.payment-authorization in the request: the Gateway returns a JSON-RPC error frame:
data.challenges array follows the MPP challenge schema (CIP-18 §9.1/§13.4), with the MCP-specific request_hash: because the Gateway synthesizes method/path/body from arguments (§11.2), the client cannot reproduce the request bytes to compute the §9.5.1 binding itself, so the challenge carries the request_hash the Gateway will enforce. The client signs it; on redemption the Gateway re-derives it from the identical re-sent arguments and verify() enforces the match (CIP-18 §13.4).
Cowboy MCP gating uses the MPP carrier defined by CIP-18 §13.6; there is no x402_compat block in this transport. x402 clients are served over the HTTP transport, which advertises x402 challenges directly.
12.3 Payment provided
Routes withpays = "caller" and a credential in _meta.payment-authorization:
- The Gateway validates the credential through the selected adapter; native Cowboy credentials use PaymentGate (CIP-18 §11).
- Confirm successful payment or authoritative entitlement consumption before dispatch, for both queries and commands (CIP-18 §6 and §15). A settlement timeout remains pending and is reconciled against the same purchase.
- On credential verification failure, return a JSON-RPC
-32402error with a fresh challenge. Do not challenge for a second payment when the first may already have settled. - After confirmation, dispatch per §11.3 under the purchase execution identity and include the receipt in
result._meta.payment-receipt. Paid execution failures follow CIP-18 recovery rules.
12.4 Pass and subscription credentials
intent="pass" and intent="subscription" credentials are carried in the same _meta.payment-authorization field. The Gateway evaluates them ahead of intent="charge" per the CIP-18 §7.5 fallback chain.
13. Reserved Tool Names
Tool names beginning with_cowboy_ (after tool_name_prefix is applied) are reserved for system tools the Gateway exposes alongside actor-derived tools. v1 reserves but does not yet implement:
A future CIP can populate these. v1 simply reserves the namespace so actor tool names cannot collide.
14. Gateway Integration
14.1 New responsibilities
The Gateway gains:- An MCP server implementation per §8 with streamable HTTP transport, JSON-RPC 2.0 framing, and session management.
- A tools-list generator that materializes
Toolentries from the routes table on session start (and, in a future revision that enableslistChanged, onnotifications/tools/list_changed). - A
tools/calltranslator that maps to the existing dispatch path. No new dispatch operations. - Hooks into CIP-18’s payment enforcement: the JSON-RPC frame inspector for
_meta.payment-authorization, the error mapper for-32402, and the receipt emitter.
14.2 No actor-side changes
Actor handler code is unchanged. An actor that already serves HTTP via CIP-14 + CIP-15 becomes MCP-callable by adding theingress.mcp entitlement. The handler receives an HTTP request envelope.
14.3 Caching
The Gateway caches the per-actor tool list keyed by(actor, routes_state_root). Cache is invalidated when the actor’s state root changes (signaled by the same state_root-polling cache refresh the Gateway already runs for the route registry (CIP-17 §6.1 verifiable routes fetch; CIP-15 v2.r2 §6 MANIFEST_POLL_INTERVAL)).
15. Reserved Paths
No new reserved paths beyond what CIP-18 already declared.
16. Protocol Constants
17. Security Considerations
- The reserved
_cowboy_*prefix prevents a tool name collision in which an actor route impersonates a system tool. Routes that would collide are dropped fromtools/list(§10.4). The dropped-route warning is observable in the Gateway’s structured-error logs. - The Gateway URL-encodes path parameters from
argumentsbefore substituting them intoroute.path(§11.2 step 3), which blocks path-parameter injection. Arguments cannot smuggle additional path segments via slashes or... - PaymentGate prevents payment replay over MCP. Each native Cowboy payment credential carries a
noncethat PaymentGate consumes atomically (CIP-18 §9.5.1). Submitting the same credential as both an HTTP retry and an MCP tool call settles once. - Payment credentials are bound to
request_hash, which prevents cross-session credential reuse. An MCP_meta.payment-authorizationissued for one tool call cannot be replayed against another. - To resist session hijacking,
Mcp-Session-Idis a server-issued opaque token withMCP_SESSION_IDLE_TIMEOUT_SECONDSlifetime. Sessions are tied to TLS-terminated connections; the Gateway rejects requests whoseMcp-Session-Idcame from a different TLS endpoint or expired. MAX_TOOL_INPUT_BYTES(governance default1 MiB) bounds tool argument size, and so attacker payload size, before any actor dispatch occurs.MAX_TOOL_OUTPUT_BYTESbounds the tool output response body. Truncation is signaled in_meta.cowboy.truncated.- The MCP
tools/listresponse cannot grow without bound; it is bounded by the routes table’sMAX_ROUTES(CIP-15 §10). Pagination is not required. - Server-initiated requests are disabled. v1 does not advertise
samplingornotifications/*capabilities. A malicious client cannot induce the Gateway to call back into it. - Routes that target the same method name with mismatched schemas are dropped (§10.1 step 4) rather than producing inconsistent tools. An attacker cannot poison
tools/listby registering a conflicting low-priority route, because the Gateway picks the canonical route deterministically. - To limit information leakage in errors, HTTP 5xx response bodies are size-bounded before inclusion in JSON-RPC
error.data. Secrets that an actor returns in 5xx bodies are a CIP-14 problem outside the scope of CIP-19; this CIP does not amplify the leak. - Tool-call arguments arrive as opaque strings from the agent’s perspective. The Gateway does not interpret tool descriptions or arguments as prompts. Prompt-injection risks live in the agent runtime and are out of scope for this CIP.
18. Rationale
MCP terminates at the Gateway. The Gateway is the public, DNS-addressable, payment-enforcing edge. Runners are private compute. Putting MCP on runners would require (a) exposing them publicly, (b) duplicating CIP-18 payment enforcement, (c) forcing actors to opt into “I’m an MCP server” beyond just declaring routes. Gateway termination preserves CIP-14’s architectural separation and makes MCP exposure free for any actor that already has HTTP routes. Why derivetools/list from the routes table? A separate MCP-tool declaration would create skew between HTTP and MCP surfaces. CIP-15’s routes table is already the authoritative description of “what this actor exposes.” Deriving the OpenAPI doc (CIP-18 §14) and the MCP tool list from the same source means an agent that uses HTTP and an agent that uses MCP see the same actor.
Why one tool per method name? Routes map a verb and path to a handler. Tools are a logical concern (named callable). Multiple routes can target the same method (e.g., GET /users/{id} and HEAD /users/{id} both target users.get); collapsing them into one tool matches the conceptual layer MCP operates at.
Why version-pin to MCP 2025-11-25? It is the current (as of 2026-04-28) MCP spec, has the streamable HTTP transport, and has stable _meta semantics required by MPP’s JSON-RPC payment transport. Earlier versions lack _meta; later versions are unspecified at this CIP’s creation. Future CIPs can advance the pin.
Why not implement MCP resources? Volume-target routes (CIP-15) are the natural backing for MCP resources (URI-addressable read-only content). Wiring this up requires careful thinking about resource templates vs. concrete URIs and the read-time consistency guarantees clients expect. Deferring keeps v1 small and lets us learn from tools-only deployment first.
Why not stream tool results in v1? SSE-style streaming changes the dispatch contract: the actor would need to emit chunks rather than a single envelope. This is conceptually compatible with CIP-7 streams but operationally requires Gateway buffering and cancellation propagation. Out of scope for the first MCP CIP.
Why a new entitlement instead of reusing ingress.http? Some actors need HTTP exposure without MCP exposure, such as web-only frontends, SEO landing pages, or actors whose route handlers were not designed for agent invocation. Making MCP opt-in via ingress.mcp lets authors decide explicitly.
19. Future Work
- Map CIP-15 Volume-target routes to MCP resources, with URI templates corresponding to wildcard paths.
- Allow actors to declare reusable prompt templates as a separate KV table, exposed via MCP
prompts/listandprompts/get. - Bridge CIP-7 streams to MCP streamed tool results.
- Add an optional
mcp_namefield on Route entries (CIP-15 schema extension) for friendlier tool names. - If actor-initiated agent interaction becomes a use case, support sampling and notifications: advertise the
samplingcapability and add a runner-side outbound MCP client. - Advance the pinned MCP version as the MCP spec evolves. CIP-12 governs the deprecation policy.
- Implement the §13 system tools (
_cowboy_payment_quote,_cowboy_payment_subscribe, etc.) so MCP-only clients can interact with PaymentGate without a separate HTTP path.
20. Backwards Compatibility
This CIP is fully additive:- Actors without
ingress.mcpare unaffected. No MCP endpoint is exposed. - Actors with
ingress.mcpand existing CIP-15 routes need no code changes. Their existing routes table supplies the tool definitions. - The
/_cowboy/mcpreserved path was reserved by CIP-18 §17. This CIP defines its semantics; it does not introduce a new reservation. - No changes to CIP-14 dispatch semantics, CIP-15 route schema, CIP-18 PaymentGate, or any other CIP.
- The MCP version pin is a Gateway-side concern; advancing it does not require an actor-side change.