AMAROK wolf mark AMAROK

MCP server

Amarok MCP is a walletless wrapper over the public Caddy gateway. Agents call typed tools for discovery, prediction-market research, and unsigned execution quotes, and handle x402 payment signing on the client side. Production agents should use the remote Streamable HTTP endpoint; local stdio is available for development against a gateway you control.

Remote endpoint (recommended)

The MCP never stores mnemonics or private keys. Paid tools return structured payment requirements on the first call; your agent signs USDC client-side and retries with paymentSignature.

The Cloudflare Worker accepts POST and DELETE on /mcp. GET /mcp returns 405 — this host does not offer an SSE stream (Streamable HTTP still works over POST). Opening the MCP URL in a browser is not a valid check; use health or /.well-known/mcp instead.

Research and execution tools

The MCP does not retain quotes, sign transactions, or submit them; gateway responses pass through to the caller.

Verify the deployment

curl -s https://amarok-mcp.compx.io/health | jq

curl -s https://amarok-mcp.compx.io/.well-known/mcp | jq

# Expect 405 — GET SSE is not offered on this Worker
curl -i -X GET https://amarok-mcp.compx.io/mcp

/.well-known/mcp should return transport: "streamable-http" and url pointing at https://amarok-mcp.compx.io/mcp.

Client setup — remote URL

Point your MCP client at the remote endpoint. No local npm package is required for production use. Copy-paste snippets also live on the website quickstart (same JSON as mcp/mcp.json.example).

Paid tools spend mainnet USDC via x402. Probe free tools first. Hosted MCP has no dry-run; in-repo tests use a stub API (npm run test -w @amarok/mcp).

Cursor

~/.cursor/mcp.json or project .cursor/mcp.json. 

{
  "mcpServers": {
    "amarok": {
      "url": "https://amarok-mcp.compx.io/mcp"
    }
  }
}

Claude Desktop

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

{
  "mcpServers": {
    "amarok": {
      "url": "https://amarok-mcp.compx.io/mcp"
    }
  }
}

See also the x402 page for payment context when using paid tools.

Client setup — local stdio

For local development, run @amarok/mcp over stdio against compose at http://127.0.0.1:8788. Same tools as remote MCP. Paid calls still settle x402 on a live Caddy gateway; use the stub e2e suite to avoid mainnet USDC. 

{
  "mcpServers": {
    "amarok": {
      "command": "npx",
      "args": [
        "tsx",
        "mcp/src/index.ts"
      ],
      "env": {
        "AMAROK_API_URL": "http://127.0.0.1:8788"
      }
    }
  }
}

From the monorepo root after npm install. Details: mcp/README.md in the repo. Prefer the remote URL for hosted agents.

Paid tool flow

  1. Call a paid tool (e.g. amarok_list_opportunities) without paymentSignature.
  2. The tool returns PAYMENT_REQUIRED metadata with gateway payment requirements (same x402 policy as direct HTTP).
  3. Your agent builds a PAYMENT-SIGNATURE payload client-side and retries the same tool with paymentSignature set.
  4. On success, the tool returns the gateway response.

This mirrors the direct HTTP flow documented on x402 payment flow and quickstart.

Available tools

Tool names match discovery mcpServer.tools.

Free tools include health, discovery, OpenAPI, and execution shapes. Paid tools include opportunities, market, quotes, scan, and execution quotes.

MCP vs direct HTTP

All paths hit the same public Caddy gateway for paid data. The MCP layer is a thin pass-through and does not call a private upstream API.