samurai/mcp

Getting started

For agent builders · 5 minutes
CONTENTS
  1. Get an API key
  2. Make your first call
  3. Register with Claude Code / MCP client
  4. SDK-free Python example
  5. Manifest discovery
  6. Handling 402 & rate limits

1. Get an API key

During the open beta, keys are issued by request. Email keys@mi-kernel2026.xyz with the agent runtime you intend to use. Each key starts with 1,000 free calls across all servers.

export SAMURAI_KEY="sk_live_..."

2. Make your first call

1
List tools on a server to confirm your key works.
curl -sS https://mcp.mi-kernel2026.xyz/causal-memory/v1 \
  -H "Authorization: Bearer $SAMURAI_KEY" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'
2
Invoke a tool.
curl -sS https://mcp.mi-kernel2026.xyz/causal-memory/v1 \
  -H "Authorization: Bearer $SAMURAI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc":"2.0","id":2,"method":"tools/call",
    "params":{"name":"lookup_exemplars","arguments":{"query":"…","k":5}}
  }'

3. Register with an MCP client

Add the server to your client's config. Example for Claude Code:

{
  "mcpServers": {
    "samurai-causal-memory": {
      "transport": "http",
      "url": "https://mcp.mi-kernel2026.xyz/causal-memory/v1",
      "headers": { "Authorization": "Bearer $SAMURAI_KEY" }
    }
  }
}

4. SDK-free Python

import os, json, urllib.request

req = urllib.request.Request(
    "https://mcp.mi-kernel2026.xyz/causal-memory/v1",
    data=json.dumps({
        "jsonrpc": "2.0", "id": 1,
        "method": "tools/call",
        "params": {
            "name": "lookup_exemplars",
            "arguments": {"query": "flaky CI", "k": 5},
        },
    }).encode(),
    headers={
        "Authorization": f"Bearer {os.environ['SAMURAI_KEY']}",
        "Content-Type": "application/json",
    },
)
with urllib.request.urlopen(req) as r:
    print(json.loads(r.read()))

5. Manifest discovery

Every server publishes a signed manifest at /.well-known/mcp-manifest.json. Agents can crawl the catalog at /.well-known/mcp-catalog.json to enumerate all live servers without hard-coding endpoints.

6. Handling 402 & rate limits

A 402 Payment Required response means your key's balance is exhausted. The body contains a top-up endpoint. Treat it as a routing signal — fall back to a cheaper server, queue, or pause.

Tip: budget by reading _meta.billed_micro_usd and _meta.balance_remaining_micro_usd from successful responses, not by polling a billing API.
HTTP/1.1 402 Payment Required
Content-Type: application/json

{ "top_up_url": "https://mcp.mi-kernel2026.xyz/billing/topup",
  "balance_micro_usd": 0 }