samurai MCP Specification

1. Scope

This document specifies the wire protocol, manifest schema, and billing semantics for a samurai MCP server — a Model Context Protocol endpoint that exposes one or more tools to autonomous agents, with per-call metered billing.

This spec extends the upstream MCP draft (2024-11-05) with a billing envelope and a discoverable manifest. It does not modify MCP semantics.

2. Transport

All servers MUST accept JSON-RPC 2.0 over HTTPS POST. The base endpoint is the server URL; a single endpoint serves all methods. Servers MAY additionally expose Server-Sent Events at {endpoint}/sse for streaming tools.

POST /v1 HTTP/1.1
Host: mcp.mi-kernel2026.xyz
Content-Type: application/json
Authorization: Bearer <api_key>

3. Authentication

Bearer tokens in the Authorization header. Tokens are scoped to one or more servers and carry rate-limit + balance metadata. Unauthenticated requests MUST receive HTTP 401. Exhausted balances MUST receive HTTP 402 with a JSON body describing the top-up endpoint — matching x402.org semantics.

4. Methods

A samurai server MUST implement, at minimum:

4.1 tools/call request

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "lookup_exemplars",
    "arguments": { "query": "…", "k": 5 }
  }
}

4.2 tools/call response

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [ { "type": "json", "data": { … tool output … } } ],
    "_meta": {
      "billed_micro_usd": 500,
      "latency_ms": 38,
      "balance_remaining_micro_usd": 9412300
    }
  }
}

5. Manifest

Every server MUST publish a manifest at {endpoint}/.well-known/mcp-manifest.json. Clients MAY cache for up to 24h. Manifests follow this schema:

{
  "name": "samurai-causal-memory",
  "version": "0.1.0",
  "description": "…",
  "endpoint": "https://mcp.mi-kernel2026.xyz/causal-memory/v1",
  "auth": { "type": "bearer" },
  "tools": [ { "name": "lookup_exemplars", "inputSchema": { … } } ],
  "pricing": {
    "free_tier_calls_per_day": 100,
    "metered_price_usd_cents": 0.05
  },
  "health_check_url": "https://mcp.mi-kernel2026.xyz/causal-memory/health"
}

6. Billing

Billing is settled per tools/call. Pricing is published in the manifest and MAY be flat or include input/output token components. Servers MUST report billed_micro_usd in the _meta envelope so clients can budget without a separate billing API. Failed calls (5xx, schema errors) MUST NOT be billed.

7. Errors

8. License

This specification is released under the MIT License. Server implementations may carry their own license; manifests MUST declare it.