@nmrtn/blacktea-mcp

MCP server exposing blacktea's pay tool to Claude Desktop, Cursor, and any other MCP-aware client. Drop one config block and your assistant gains a typed pay tool with full policy + audit enforcement.

Tools exposed

| Tool | What it does | |---|---| | pay | Make a paid HTTP request via x402. Library applies your policy before signing; large or unusual payments may require approval. Returns the response body and a payment receipt. | | audit_query | Read recent payment events from the audit log. Useful when the assistant needs to explain what was paid for or how much was spent today. |

Install

You do not install it permanently. The MCP client spawns it on demand via npx. Configure once per client.

Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows). Add under mcpServers:

{
  "mcpServers": {
    "blacktea": {
      "command": "npx",
      "args": ["-y", "@nmrtn/blacktea-mcp"],
      "env": {
        "EVM_PRIVATE_KEY": "0xYourBaseSepoliaPrivateKey",
        "BLACKTEA_POLICY": "/absolute/path/to/policy.json",
        "BLACKTEA_CHAIN": "base-sepolia"
      }
    }
  }
}

Restart Claude Desktop. The new tool appears in the tool list. Ask "use the pay tool to fetch <some x402 URL>" and watch.

Cursor

In Cursor settings, add an MCP server with the same shape: npx -y @nmrtn/blacktea-mcp, and the same env vars.

Cline / Continue / other MCP-aware clients

Same pattern. The MCP standard is consistent across clients.

Configuration env vars

| Env var | Required | Default | What | |---|---|---|---| | EVM_PRIVATE_KEY | yes | none | 0x-prefixed wallet private key. Holds USDC for payments. | | BLACKTEA_POLICY | no | ./policy.json | Path to the policy file. Use an absolute path; relative paths resolve from wherever the MCP client spawns the server. | | BLACKTEA_CHAIN | no | base-sepolia | EVM chain identifier passed to x402. Use base for mainnet. | | BLACKTEA_HISTORY | no | ./.blacktea/history.jsonl | Path to the JSONL audit log. |

What a policy file looks like

See docs/policy-cookbook.md in the main repo for the full DSL reference. Quick example:

{
  "rules": [
    { "if": { "amount_gte": 5 },   "then": { "reject": "absolute_cap" } },
    { "if": { "amount_lt": 0.1 },  "then": { "approve": true } },
    { "if": { "amount_gte": 0.1 }, "then": { "approval": "console" } }
  ],
  "default": { "approval": "console" }
}

Save it somewhere stable (e.g. ~/.config/blacktea/policy.json) and point BLACKTEA_POLICY at it.

What this does NOT do

• It does not hold your private key for you. The key stays on your machine; we never see it.
• It does not include a UI for approval prompts. v0.0.1 uses the console channel which prompts on stderr; for Slack/SMS/etc, the caller of the underlying library can supply an onApprovalNeeded callback (SDK path, not yet exposed through MCP).

See also

• Main repo: github.com/nmrtn/blacktea
• Library: npm install @nmrtn/blacktea
• Policy cookbook: docs/policy-cookbook.md

License

MIT.