@bitbooth/mcp-routes

@bitbooth/mcp-routes

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.0"],
      "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.0

Global install

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

Tools

Tool	Effect
list_routes	List the authenticated seller's routes and saved payout configuration
create_route	Create or replace a method-bound x402 route
update_route	Idempotently upsert a route by path
delete_route	Delete a route by path
preview_route	Return the exact x402 v2 resource.url and accepts[] without charging

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

Mode	Network	Asset and requirements
test	eip155:84532	Base Sepolia USDC; requires an EVM payout address
live	eip155:8453	Base mainnet USDC; requires an EVM payout address
live	solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp	Solana mainnet USDC; requires a valid Solana public key and gateway fee-payer configuration
live	xrpl:0	XRPL mainnet USDC; requires the exact payout address and explicit pinned-issuer trustline confirmation; availability remains deployment-gated
live	stellar:pubnet	Stellar pubnet USDC; requires the exact payout address and explicit pinned-issuer trustline confirmation

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

Environment variable	Description	Default
BITBOOTH_API_KEY	Tenant management API key (x402_…), required	—
BITBOOTH_BASE_URL	BitBooth gateway URL	https://app.heinrichstech.com

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