@katanga/sdk-mcp

Model Context Protocol server exposing Katanga marketplace primitives to LLM-driven agents. Connect Claude Desktop, Claude Code, or any MCP-compatible runtime and the agent can read listings, fetch supplier reputation, surface trajectories + HITL queue, and execute purchases / fulfillments using a configured wallet.

Built for the GH-600 brief — agents using MCP to drive Katanga.

Install

pnpm add @katanga/sdk-mcp
# or globally:
npm install -g @katanga/sdk-mcp

After install the katanga-mcp bin is on the PATH.

Configure (Claude Desktop)

In claude_desktop_config.json (macOS: ~/Library/Application Support/Claude/, Windows: %APPDATA%\Claude\):

{
  "mcpServers": {
    "katanga": {
      "command": "katanga-mcp",
      "env": {
        "KATANGA_CHAIN_ID": "114",
        "KATANGA_RPC_URL": "https://coston2-api.flare.network/ext/C/rpc"
      }
    }
  }
}

Restart Claude Desktop. The Katanga tools appear in the tool palette.

Configure (Claude Code)

~/.claude/mcp_settings.json:

{
  "mcpServers": {
    "katanga": {
      "command": "katanga-mcp"
    }
  }
}

Environment variables

| Var | Default | Purpose | |---|---|---| | KATANGA_CHAIN_ID | 114 (Coston2) | Flare chain id (14 for mainnet) | | KATANGA_RPC_URL | Coston2 default | Flare RPC endpoint | | KATANGA_MARKET_ADDRESS | Coston2 deployment | KatangaMarket address | | KATANGA_ESCROW_ADDRESS | Coston2 deployment | KatangaEscrow address | | KATANGA_REPUTATION_ADDRESS | Coston2 deployment | KatangaReputation address | | KATANGA_PAYMENT_TOKEN | eUSDT on Coston2 | ERC-20 payment token for purchases | | KATANGA_MCP_TRANSPORT | stdio | stdio (Claude Desktop / IDE) or http (network) | | KATANGA_MCP_HTTP_PORT | 3737 | HTTP port (when transport=http) | | KATANGA_MCP_API_KEY | (unset) | Bearer token required for HTTP transport in production | | KATANGA_MCP_BUYER_PRIVATE_KEY | (unset) | 0x-prefixed private key — enables katanga_purchase + katanga_confirm_delivery | | KATANGA_MCP_SUPPLIER_PRIVATE_KEY | (unset) | 0x-prefixed private key — enables supplier write tools | | KATANGA_MCP_SUPABASE_URL | (unset) | Supabase project URL — enables service-role read tools | | KATANGA_MCP_SUPABASE_SERVICE_KEY | (unset) | Service-role key — must pair with the URL | | KATANGA_MCP_AUTONOMY_LEVEL | L3 | Reserved — autonomy gating not enforced in MCP v1 (Q2 ratification: default L3, env-configurable). | | KATANGA_MCP_HITL_BACKEND | noop | Reserved for future HITL wiring. | | KATANGA_MCP_TRAJECTORY_BACKEND | noop | noop / console (stderr JSONL) — Supabase emitter wired in a follow-on EP. |

Available tools

Read (always registered)

• katanga_list_listings — filter by category or supplier address
• katanga_get_listing — by id
• katanga_get_supplier — registration + reputation
• katanga_get_escrow — state + parties + amount

Read (require KATANGA_MCP_SUPABASE_*)

• katanga_recent_runs — agent runs grouped by run_id
• katanga_get_run — full timeline + linked parent + children
• katanga_pending_hitl — operator queue

Write — buyer (require KATANGA_MCP_BUYER_PRIVATE_KEY)

• katanga_purchase — approve + createEscrow in one shot
• katanga_confirm_delivery — release escrow

Write — supplier (require KATANGA_MCP_SUPPLIER_PRIVATE_KEY)

• katanga_create_listing
• katanga_deactivate_listing
• katanga_accept_order
• katanga_mark_shipped

Resources (require supabase)

• katanga://run/{runId} — full trajectory JSON suitable for attachment as conversation context, PR comment, or issue artifact.

Role-gated by design

Each role's write tools only register when its private key is configured. A buyer-only deployment cannot accidentally expose supplier writes (and vice versa) — the tool simply isn't on the registered list.

Security

• Stdio transport: implicit trust (whoever has stdio access to the process is the operator).
• HTTP transport: bearer token via KATANGA_MCP_API_KEY. The config loader fail-closes in production if HTTP is selected without an API key — exposing wallet writes over the network without auth is a wallet-write footgun.
• Service role key: read directly from env, never logged, never bundled to a client.
• Wallet private keys: read directly from env, never logged.

Run locally

KATANGA_MCP_TRAJECTORY_BACKEND=console katanga-mcp

The server prints registration info to stderr; stdout is reserved for the MCP protocol.

Tests

pnpm test