@bitbooth/mcp-routes

npm version MCP Registry MIT license

Manage your private BitBooth x402 seller routes from Claude, Codex, Cursor, or any other MCP client. The server exposes tools to create, list, update, delete, and preview routes through BitBooth's authenticated /v1/routes API.

Tenant routes are intentionally unlisted. This package does not publish them into BitBooth's public catalog. Run preview_route and share its exact resource.url with buyers or invoke it from your own agent integration.

Every create, update, and delete call automatically carries a fresh UUIDv4 Idempotency-Key. BitBooth scopes that key to the authenticated seller, stores only request hashes, replays an exact completed mutation, and rejects changed reuse before touching DynamoDB or Secrets Manager.

Install

Get a tenant API key by signing in at app.heinrichstech.com/portal. Keep it in your MCP client's environment; do not put it in prompts or source control.

Claude Desktop, Cursor, Windsurf, or Continue

{
  "mcpServers": {
    "bitbooth-routes": {
      "command": "npx",
      "args": ["-y", "@bitbooth/mcp-routes@1.1.1"],
      "env": {
        "BITBOOTH_API_KEY": "x402_<your-tenant-api-key>"
      }
    }
  }
}

Claude Code

claude mcp add bitbooth-routes --env BITBOOTH_API_KEY=x402_<your-tenant-api-key> -- npx -y @bitbooth/mcp-routes@1.1.1

Global install

npm install -g @bitbooth/mcp-routes@1.1.1
export BITBOOTH_API_KEY="x402_<your-tenant-api-key>"
mcp-routes

Tools

Example requests:

• "Create a POST route at /api/forecast for 0.01 USDC in test mode, paid to my Base Sepolia wallet."
• "Change /api/forecast to GET and make it live on Base mainnet."
• "Preview /api/forecast and give me its agent-callable URL and wire amounts."

Route contract

Prices use the API's legacy priceWei field name, but the value is a strictly positive string of six-decimal USDC atomic units. For example, "10000" means 0.01 USDC.

{
  "path": "/api/forecast",
  "method": "POST",
  "priceWei": "10000",
  "asset": "USDC",
  "mode": "live",
  "tenantPayTo": {
    "eip155:8453": "0x1234567890123456789012345678901234567890"
  },
  "upstreamUrl": "https://api.example.com/forecast",
  "upstreamAuth": {
    "type": "bearer",
    "value": "your-write-only-upstream-token"
  }
}

• method is one of GET, POST, PUT, PATCH, DELETE, or HEAD; it defaults to POST. A different request method is rejected before BitBooth issues or settles payment.
• path must start with /, contain at least one non-empty segment, and contain no query, fragment, empty segment, or ./.. segment.
• mode defaults to test. Test routes advertise only Base Sepolia; live routes advertise eligible mainnet rails.
• tenantPayTo accepts only the exact network identifiers below. A missing network is omitted from accepts[]; it never falls back to a BitBooth wallet.
• upstreamUrl must be a public URL. Live routes and every route that uses upstream authentication require HTTPS; plain HTTP is accepted only for unauthenticated test-mode routes. Omit it on update to preserve the saved upstream, or send null to disconnect it.
• upstreamAuth is write-only. Omit it on update to preserve the credential, send a replacement to rotate it, or send null to clear it. Route responses expose only upstreamAuthConfigured.

Secure upstream authentication

BitBooth can authenticate paid deliveries to an upstream with either a bearer token or a safe custom header:

{
  "upstreamAuth": {
    "type": "bearer",
    "value": "private-token"
  }
}

{
  "upstreamAuth": {
    "type": "header",
    "headerName": "x-upstream-token",
    "value": "private-value"
  }
}

On create, value and upstreamUrl are required when authentication is configured. On update:

• Omit upstreamAuth to preserve the current configuration.
• Send { "type": "bearer" } or { "type": "header", "headerName": "x-new-name" } without value to reuse an existing credential while changing how it is injected.
• Include value to set or replace the credential.
• Send null to clear the credential.
• Changing the upstream origin requires a replacement credential or an explicit auth clear. Disconnecting the upstream also clears its credential.

Custom header names are normalized to lowercase. BitBooth rejects transport, payment, cookie, tracing, AWS/CloudFront, proxy, browser-security, Authorization, and X-API-Key headers. Credential values cannot be empty, padded with whitespace, contain control characters, or exceed 8,192 characters. Bearer tokens use the RFC 6750-compatible token character set.

Credential values are sent only in the authenticated management write, stored in AWS Secrets Manager, and never returned by list/create/update/preview tools or included in surfaced errors. A route response reports only "upstreamAuthConfigured": true or false.

Supported payout networks

XRPL and Stellar opt-ins use this exact shape. Other issuers, assets, and networks are rejected.

{
  "tenantPayTo": {
    "xrpl:0": "rfryheo6yzFdLWj8qUQtZc7zG9MKkBkUEy",
    "stellar:pubnet": "GDIK4RML4K63ZI3SYGJD5TL4ILEAZT3LBY7MXJJP5YSSZ5O4DTHDOIA3"
  },
  "tenantStablecoinRails": {
    "xrpl:0": {
      "asset": "USDC",
      "issuer": "rGm7WCVp9gb4jZHWTEtGUr4dd74z2XuWhE",
      "trustlineConfirmed": true
    },
    "stellar:pubnet": {
      "asset": "USDC",
      "issuer": "GA5ZSEJYB37JRC5AVCIA5MOP4RHTM335X2KGX3IHOJAPP5RE34K4KZVN",
      "trustlineConfirmed": true
    }
  }
}

The preview response is x402 v2. Read the callable URL from resource.url and the per-rail wire amount from each accepts[].amount; wire units can differ by rail.

Configuration

Programmatic use

import { createApiClient } from '@bitbooth/mcp-routes/api-client';

const api = createApiClient({ apiKey: process.env.BITBOOTH_API_KEY });
const { routes } = await api.listRoutes();
const challenge = await api.previewRoute(routes[0].path);
console.log(challenge.resource.url, challenge.accepts);

The client validates BitBooth responses before returning them and redacts the management API key from surfaced transport and API errors.

License

MIT