CIP-19: Gateway MCP Ingress

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.

​

1. Abstract

• Hosts an MCP server at https://<actor>.cowboy.network/_cowboy/mcp using MCP’s streamable HTTP transport (spec version 2025-11-25).
• Auto-generates the tools/list response 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 ride JSON-RPC error code -32402; credentials and receipts ride the MCP _meta field.

• MCP resources and prompts. v1 is tools-only.
• Streaming tool results. SSE-style streaming is acknowledged but deferred to a follow-on CIP.
• Custom tool name remapping. Tool names are derived mechanically from route method names.
• Server-initiated notifications and sampling.

​

2. Motivation

1. Verifiable tools. An MCP tool backed by a Cowboy actor has on-chain, deterministic code. An agent can audit what the tool actually does before calling it.
2. Natively payable. Combined with CIP-18, an MCP tool call can require payment up front. Agents that already speak the JSON-RPC payment transport Just Work.
3. Self-sovereign. No hosting provider, no API key issuance, no DNS acrobatics. Deploy an actor, grant ingress.http and ingress.mcp, and you have a payable MCP server reachable at <actor>.cowboy.network/_cowboy/mcp.
4. Discoverable. The CIP-18 OpenAPI document and the MCP tools/list come from the same source — the routes table — so agents can discover Cowboy actors through whichever surface they prefer.

​

3. Design Goals

• Zero actor opt-in for the wire. An actor author declares routes (CIP-15). The Gateway exposes those routes as MCP tools. The handler code is unchanged.
• One source of truth. Tool list is derived from the routes table. The CIP-18 OpenAPI document is generated from the same data. Skew is impossible.
• Same dispatch as HTTP. A tools/call invocation dispatches through CIP-14’s existing query/command paths. No new actor-side execution model.
• Payment via CIP-18. MCP gating reuses CIP-18 wire formats over MPP’s JSON-RPC transport. No new payment code path.
• Gateway-terminated, not runner-terminated. Mirrors CIP-14: the Gateway is the public edge, runners are private compute.
• Standard MCP wire. The Gateway speaks unmodified MCP 2025-11-25 over streamable HTTP. Any conformant MCP client works.

​

4. Non-goals

• MCP resources and prompts. Tools only in v1. CIP-15 volumes could plausibly back resources in a future revision.
• Streaming tool results. SSE / chunked tool results are deferred; v1 returns one response per call.
• Server-initiated requests. MCP supports server → client sampling/createMessage and notifications/*. v1 does not implement these.
• Tool name customization. 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. OAuth, API keys, and other MCP auth modes are out of scope. Payment is the only gating mechanism in v1.
• Actor-side MCP client. This CIP is about actors as MCP servers. Actor consumption of external MCP servers (the existing runner-mcp crate) is unrelated.

​

5. Definitions

• MCP: The Model Context Protocol, version 2025-11-25 (the spec dated 2025-11-25 on modelcontextprotocol.io). Uses JSON-RPC 2.0 framing.
• Streamable HTTP transport: MCP’s HTTP-based transport mode (replaces the older HTTP+SSE transport from earlier MCP revisions).
• Tool: 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.
• Tool name: The string identifying a tool. Derived from route.target.name per §10.
• MCP _meta field: A reserved JSON-RPC field for protocol extensions. Used by CIP-18 to carry payment credentials and receipts.

​

6. Architecture

                  ┌──────────────────────────────────────────┐
                  │           MCP client (agent)             │
                  └────────────┬─────────────────────────────┘
                               │ JSON-RPC over streamable HTTP
                               ▼
       https://<actor>.cowboy.network/_cowboy/mcp
                               │
                  ┌────────────▼─────────────────────────────┐
                  │              Gateway                     │
                  │                                          │
                  │  • terminates MCP                        │
                  │  • generates tools/list from routes      │
                  │  • enforces payment (via CIP-18 §13)     │
                  │  • translates tools/call → dispatch      │
                  └────────────┬─────────────────────────────┘
                               │  same dispatch as HTTP
                               │  (CIP-14 query/command path)
                               ▼
                  ┌──────────────────────────────────────────┐
                  │              Compute Runner              │
                  │  (actor handler, unchanged)              │
                  └──────────────────────────────────────────┘

​

7. The ingress.mcp Entitlement

EntitlementGrant {
    id: "ingress.mcp",
    params: {
        "server_name":            string?,        // overrides default
        "server_instructions":    string?,        // human-readable, shown in initialize
        "tool_name_prefix":       string?,        // optional namespace, e.g. "myapp_"
        "exclude_routes":         [string]?,      // method names not to expose
        "max_tool_input_bytes":   u32?            // governance default if omitted
    }
}

​

8. MCP Endpoint

https://<actor>.cowboy.network/_cowboy/mcp

​

8.1 Session lifecycle

• 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).

​

9. Capability Negotiation (initialize)

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "protocolVersion": "2025-11-25",
    "serverInfo": {
      "name": "<actor>.cowboy.network",
      "version": "<actor-onchain-block-height>"
    },
    "capabilities": {
      "tools": { "listChanged": true }
    },
    "instructions": "<from ingress.mcp.server_instructions, or empty>"
  }
}

​

10. tools/list

​

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

{
  "name": "<tool_name_prefix><method-name-mcp-safe>",
  "description": "<from OpenAPI summary, or auto-generated from path/verb>",
  "inputSchema": {
    "type": "object",
    "properties": {
      "<path-param-1>": { "type": "string", "description": "Path parameter" },
      "<query-param-1>": { "type": "string", "description": "Query parameter" },
      "body":            { "$ref": "#/$defs/<body-schema>" }
    },
    "required": [...path params...]
  },
  "_meta": {
    "cowboy": {
      "verb":   "POST",
      "path":   "/api/users/{user_id}",
      "pays":   "caller",
      "price":  "0.05 CBY"
    }
  }
}

​

10.3 Input schema derivation

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. No declared schema → fall back to a permissive additionalProperties: true object.

​

10.4 Tool name mapping

tool_name = ingress.mcp.tool_name_prefix + sanitize(route.target.name)

​

11. tools/call (Dispatch Contract)

​

11.1 Request shape

{
  "jsonrpc": "2.0",
  "id": 7,
  "method": "tools/call",
  "params": {
    "name": "users_get",
    "arguments": {
      "user_id": "abc123",
      "verbose": "true"
    },
    "_meta": {
      "payment-authorization": "<base64url-mpp-credential>"   // optional, see §12
    }
  }
}

​

11.2 Translation to HTTP equivalent

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.5) with:
   • verb = route.verb (or POST if route.verb == "ANY")
   • 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

• Safe verbs (GET, HEAD): CIP-14 query path via read_handler. No transaction, no consensus.
• Unsafe verbs (POST, PUT, PATCH, DELETE): CIP-14 command path via GatewayRegistry.dispatch(). Consensus-required.

​

11.4 Response shape

{
  "jsonrpc": "2.0",
  "id": 7,
  "result": {
    "content": [
      { "type": "text", "text": "<actor response body, decoded>" }
    ],
    "isError": false,
    "_meta": {
      "payment-receipt": "<base64url-mpp-receipt>",         // when paid
      "cowboy": {
        "status":     200,
        "block":      <block_height>,
        "tx_hash":    "<command-path only>"
      }
    }
  }
}

• content-type: application/json → emit as a single text content block with the JSON, AND a sibling structuredContent field carrying the parsed JSON (per MCP 2025-11-25).
• content-type: text/* → emit as a single text content block.
• Binary types (image/*, application/octet-stream) → emit as 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

• HTTP 4xx (other than 402): result.isError = true, content describes the error, no JSON-RPC error frame.
• HTTP 5xx: JSON-RPC error frame with code = -32603 (internal error), message = "Actor handler failed", data carrying the response body if size-bounded.
• HTTP 402: see §12.
• Network / timeout: JSON-RPC error frame with code = -32000, message = "Gateway dispatch failed".

​

12. Authentication and Payment

​

12.1 No payment required

​

12.2 Payment required, no credential

{
  "jsonrpc": "2.0",
  "id": 7,
  "error": {
    "code": -32402,
    "message": "Payment Required",
    "data": {
      "challenges": [
        {
          "id": "<hmac-bound-id>",
          "realm": "<actor>.cowboy.network",
          "method": "cowboy",
          "intent": "charge",
          "expires": "...",
          "request": "<base64url(JCS-JSON)>"
        }
      ],
      "x402_compat": {
        "accepts": [ ... ]
      }
    }
  }
}

​

12.3 Payment provided

1. The Gateway normalizes the credential to a PaymentIntent per CIP-18 §11.
2. PaymentGate verifies and (atomically with dispatch on the command path, or fire-and-forget on the query path) settles per CIP-18 §15.
3. On verification failure, the Gateway returns a JSON-RPC -32402 error with a fresh challenge.
4. On success, the Gateway dispatches per §11.3 and includes the receipt in result._meta.payment-receipt.

​

12.4 Pass and subscription credentials

​

13. Reserved Tool Names

​

14. Gateway Integration

​

14.1 New responsibilities

• An MCP server implementation per §8 — streamable HTTP transport, JSON-RPC 2.0 framing, session management.
• A tools-list generator that materializes Tool entries from the routes table on session start and on notifications/tools/list_changed.
• A tools/call translator that maps to the existing dispatch path. No new dispatch primitives.
• 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

​

14.3 Caching

​

15. Reserved Paths

​

16. Protocol Constants

MCP_PROTOCOL_VERSION              = "2025-11-25"
MCP_SESSION_IDLE_TIMEOUT_SECONDS  = 600           // 10 min
MAX_TOOL_INPUT_BYTES_DEFAULT      = 1_048_576     // 1 MiB
MAX_TOOL_OUTPUT_BYTES             = 4_194_304     // 4 MiB
JSONRPC_PAYMENT_REQUIRED_CODE     = -32402        // mirrors CIP-18 §19
JSONRPC_INTERNAL_ERROR_CODE       = -32603
JSONRPC_GATEWAY_DISPATCH_FAILED   = -32000
TOOLS_LIST_CHANGED_DEBOUNCE_MS    = 250

​

17. Security Considerations

• Tool name collision. Reserved _cowboy_* prefix prevents actor routes from impersonating system tools. Routes that would collide are dropped from tools/list (§10.4). The dropped-route warning is observable in the Gateway’s structured-error logs.
• Path-parameter injection. Path parameters from arguments are URL-encoded before substitution into route.path (§11.2 step 3). Arguments cannot smuggle additional path segments via slashes or ...
• Payment replay over MCP. Each MPP credential carries a nonce consumed atomically by PaymentGate (CIP-18 §21). Submitting the same credential as both an HTTP retry and an MCP tool call settles once.
• Cross-session credential reuse. Payment credentials are bound to request_hash; an MCP _meta.payment-authorization issued for one tool call cannot be replayed against another.
• 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.
• Tool argument size. MAX_TOOL_INPUT_BYTES (governance default 1 MiB) bounds attacker payload size before any actor dispatch occurs.
• Tool output size. MAX_TOOL_OUTPUT_BYTES bounds the response body. Truncation is signaled in _meta.cowboy.truncated.
• Unbounded tools/list. The MCP tools/list response 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.
• Schema mismatch DoS. 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.
• Information leakage in errors. HTTP 5xx response bodies are size-bounded before inclusion in JSON-RPC error.data. Actors that return secrets in 5xx bodies have a CIP-14 problem, not a CIP-19 problem; this CIP does not amplify the leak.
• Prompt injection. 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

​

19. Future Work

• Resources. Map CIP-15 Volume-target routes to MCP resources, with URI templates corresponding to wildcard paths.
• Prompts. Allow actors to declare reusable prompt templates as a separate KV table, exposed via MCP prompts/list and prompts/get.
• Streaming. Bridge CIP-7 streams to MCP streamed tool results.
• Tool name customization. An optional mcp_name field on Route entries (CIP-15 schema extension) for friendlier names.
• Sampling and notifications. If actor-initiated agent interaction becomes a use case, advertise the sampling capability and add a runner-side outbound MCP client.
• MCP version progression. Pin advancement as the MCP spec evolves. Deprecation policy is governed by CIP-12.
• System tools (§13). Implement _cowboy_payment_quote, _cowboy_payment_subscribe, etc., so MCP-only clients can interact with PaymentGate without a separate HTTP path.

​

20. Backwards Compatibility

• Actors without ingress.mcp are unaffected. No MCP endpoint is exposed.
• Actors with ingress.mcp and existing CIP-15 routes need no code changes — the routes table is the source of truth and is already populated.
• 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 migration.