Skip to main content
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-authorization carrier, and -32402 error 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. The ingress.mcp entitlement enables this behavior. The Gateway:
  • Hosts an MCP server at https://<0xactor>.canyon.cowboylabs.net/_cowboy/mcp using MCP’s streamable HTTP transport (spec version 2025-11-25).
  • Generates tools/list from the actor’s CIP-15 routes table. Every Method-target route becomes one MCP tool.
  • Translates tools/call invocations 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 _meta field.
This CIP defers the following:
  • 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:
  1. An agent can audit an actor tool’s on-chain, deterministic code before calling it.
  2. CIP-18 allows an MCP tool to require payment before invocation through the JSON-RPC payment transport.
  3. An actor with ingress.http and ingress.mcp exposes a payable MCP server at <0xactor>.canyon.cowboylabs.net/_cowboy/mcp without a separate hosting provider or API key issuance.
  4. The Gateway derives the CIP-18 OpenAPI document and MCP tools/list from the routes table. Agents can use either to discover actor endpoints.
The Gateway handles MCP transport for actors under CIP-14. Authors do not need to run a separate MCP server for each actor.

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/call through 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-25 over 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/createMessage and notifications/* 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 explicit mcp_name override.
  • 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-mcp crate) 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.name per §10.
  • The MCP _meta field is reserved for protocol extensions. CIP-18 uses it to carry payment credentials and receipts.

6. Architecture

The Gateway is the only new actor in this picture. Runners and actor handlers are unchanged.

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:
The endpoint speaks MCP 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 a Mcp-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 (always 2025-11-25 in v1).
  • The client’s clientInfo.
  • The cached routes-table version observed at session start (for consistent tools/list).
Session state MUST NOT contain payment state. PaymentGate stores payment state.

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

  1. Read the routes table at __cowboy/routes from the actor’s KV state (using the CIP-15 §8.12 Gateway-to-full-node fetch protocol).
  2. Filter to routes where:
    • target.kind == "method" (Volume targets are not tools)
    • enabled == true
    • target.name is not in ingress.mcp.exclude_routes
  3. Group routes by target.name. Each unique method name produces one tool.
  4. 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.
  5. Emit one Tool entry per group.

10.2 Tool entry shape

The _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:
  1. Path parameters from route.path (CIP-15 §6.3). Each {param} becomes a required string property.
  2. 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.
  3. If no schema is declared, fall back to a permissive additionalProperties: true object.
If multiple routes target the same method name (e.g., 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:
  1. Looks up the route group for params.name (reverse of §10.1).
  2. Picks the canonical route in the group (highest priority; ties broken by storage order).
  3. Substitutes path parameters from arguments into route.path.
  4. Splits remaining arguments into query parameters and body per the OpenAPI schema for the selected verb.
  5. Constructs a synthetic HttpRequestEnvelope (CIP-14 §8.1) with:
    • verb = route.verb. A route with verb == "ANY" is dispatched as POST (defaulting to the unsafe/command path when route mode is absent, §11.3): a tools/call cannot signal HTTP safety, so ANY defaults conservatively to state-mutating. Without an explicit route mode, actors wanting a safe (query-path, no-consensus, cheaper) MCP tool MUST register the route with an explicit safe verb (GET/HEAD) rather than ANY. An explicit mode selects the dispatch path independently of the normalized verb.
    • path = the substituted path
    • query = serialized query parameters
    • body = serialized body (JSON, unless OpenAPI declares otherwise)
    • headers = a synthesized minimal set (content-type, accept, plus X-Cowboy-Mcp-Session-Id)
    • path_params = the matched named parameters

11.3 Dispatch

The Gateway resolves the route mode 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 Read mode uses the unsigned CIP-14 query path via read_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 is GatewayRegistry.dispatch(); CIP-14 §8.4.1 distinguishes that contract from the direct ExecuteActor path.
Payment enforcement happens before dispatch per §12 below.

11.4 Response shape

The actor handler returns an HttpResponseEnvelope (CIP-14 §8.2). The Gateway maps it to MCP:
The Gateway interprets the response body as follows:
  • For content-type: application/json, emit a single text content block with the JSON and a sibling structuredContent field carrying the parsed JSON (per MCP 2025-11-25).
  • For content-type: text/*, emit a single text content block.
  • For binary types (image/*, application/octet-stream), emit one image or resource content block per MCP’s content-type rules. Bodies exceeding MAX_TOOL_OUTPUT_BYTES are truncated and the response is marked isError: true with a truncated flag in _meta.cowboy.

11.5 Error mapping

  • For HTTP 4xx other than 402, set result.isError = true and 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", data carrying 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 with pays = "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 with pays = "caller" and no _meta.payment-authorization in the request: the Gateway returns a JSON-RPC error frame:
The 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 with pays = "caller" and a credential in _meta.payment-authorization:
  1. The Gateway validates the credential through the selected adapter; native Cowboy credentials use PaymentGate (CIP-18 §11).
  2. 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.
  3. On credential verification failure, return a JSON-RPC -32402 error with a fresh challenge. Do not challenge for a second payment when the first may already have settled.
  4. 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 Tool entries from the routes table on session start (and, in a future revision that enables listChanged, on notifications/tools/list_changed).
  • A tools/call translator 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 the ingress.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 from tools/list (§10.4). The dropped-route warning is observable in the Gateway’s structured-error logs.
  • The Gateway URL-encodes path parameters from arguments before substituting them into route.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 nonce that 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-authorization issued for one tool call cannot be replayed against another.
  • To resist session hijacking, Mcp-Session-Id is a server-issued opaque token with MCP_SESSION_IDLE_TIMEOUT_SECONDS lifetime. Sessions are tied to TLS-terminated connections; the Gateway rejects requests whose Mcp-Session-Id came from a different TLS endpoint or expired.
  • MAX_TOOL_INPUT_BYTES (governance default 1 MiB) bounds tool argument size, and so attacker payload size, before any actor dispatch occurs.
  • MAX_TOOL_OUTPUT_BYTES bounds the tool output response body. Truncation is signaled in _meta.cowboy.truncated.
  • The MCP tools/list response cannot grow without bound; it is bounded by the routes table’s MAX_ROUTES (CIP-15 §10). Pagination is not required.
  • Server-initiated requests are disabled. v1 does not advertise sampling or notifications/* 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/list by 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 derive tools/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/list and prompts/get.
  • Bridge CIP-7 streams to MCP streamed tool results.
  • Add an optional mcp_name field 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 sampling capability 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.mcp are unaffected. No MCP endpoint is exposed.
  • Actors with ingress.mcp and existing CIP-15 routes need no code changes. Their existing routes table supplies the tool definitions.
  • The /_cowboy/mcp reserved 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.