@maxwellintl/x402-mcp

Maxwell Directory (x402 + MCP)

An MCP server for Maxwell International's pay-per-call API: ski and travel data (lift-ticket prices, trip plans, restaurants and menus near resorts, US weather), public records (company registers, SEC filings, legislation, open data, sanctions, court opinions, patents, openFDA, CVEs, economic series) and x402 tools (payment diagnosis, domain lookups, npm facts, token safety, maxwell-chat).

Free tools (product search, price quotes, coverage, trip maps) cost nothing. Paid tools cost $0.002 to $1 per call, paid in USDC on Base or Solana from your own wallet, and only within the caps you set.

Use with Claude Desktop, Claude Code or Cursor

{
  "mcpServers": {
    "maxwell": {
      "command": "npx",
      "args": ["-y", "@maxwellintl/x402-mcp"],
      "env": {
        "MAXWELL_WALLET_KEY_FILE": "/path/to/base-wallet.key",
        "MAXWELL_SOLANA_KEY_FILE": "/path/to/solana-wallet.json",
        "MAXWELL_MAX_PER_CALL_USD": "0.05",
        "MAXWELL_SESSION_BUDGET_USD": "1",
        "MAXWELL_DAILY_BUDGET_USD": "2"
      }
    }
  }
}

Claude Code: claude mcp add maxwell -e MAXWELL_WALLET_KEY_FILE=/path/to/base-wallet.key -- npx -y @maxwellintl/x402-mcp

Without a wallet the server still works: free tools answer, and paid tools return their exact price instead of buying.

Wallet safety

• Use a small, dedicated hot wallet holding only a few dollars of USDC (on Base, Solana, or both). Never your main wallet.
• Solana: you need USDC only, no SOL; the network fee is paid by the payment facilitator.
• Put the key in a file (chmod 600) and point MAXWELL_WALLET_KEY_FILE at it. MAXWELL_WALLET_KEY works but puts the key in your client's config file.
• The key stays on your machine. It is never logged, printed or returned in tool output.

Settings

Variable	Default	Meaning
MAXWELL_WALLET_KEY_FILE	none	File holding a Base (EVM) private key
MAXWELL_SOLANA_KEY_FILE	none	File holding a Solana secret key (solana-keygen JSON array or base58 export)
MAXWELL_NETWORK	base	Preferred network when both wallets are set (base or solana); the other is the fallback
MAXWELL_SOLANA_RPC_URL	public RPC	Your own Solana RPC, if the public one rate-limits you
MAXWELL_MAX_PER_CALL_USD	0.05	Calls above this need the user's OK. Clients that can ask the user (MCP elicitation) always ask; for others the call needs confirm_over_cap: true
MAXWELL_SESSION_BUDGET_USD	1	Total per server run
MAXWELL_DAILY_BUDGET_USD	2	Total per UTC day, saved in ~/.maxwell-x402-mcp/spend.json
MAXWELL_DRY_RUN	off	1 = quote only, never pay
MAXWELL_TOOLSETS	all	directory (first-party local providers worldwide), travel, records, tools, or a comma list
MAXWELL_API_BASE	https://api.maxwellinternational.ai	API to use

No single call is ever paid above $5, whatever the settings. If the spend file cannot be written (set MAXWELL_STATE_DIR to a writable folder), paid tools only quote. Several clients running the package on one machine share the daily cap.

How paying works

• The tool builds the API request and checks the required inputs (a call that would miss is refused before paying).
• The API's 402 quote gives the exact price. The budget caps are checked.
• The payment is signed with your wallet and sent once. A lost answer is never paid for again automatically.
• The result includes payment (price, transaction, what is left of your budgets). Calls the API does not charge for (misses, refusals such as weather outside the US) come back with charged: false and cost nothing.

Remote endpoint

https://api.maxwellinternational.ai/mcp (Streamable HTTP) serves the same tools to hosted agents. It holds no wallet: paid tools use the x402 MCP transport (payment requirements in the tool result, your client re-calls with _meta["x402/payment"]). Clients without x402 support should use this package.

Development

npm ci && npm run build
npm test                          # unit tests (no network)
node test/live.mjs local          # live checks through a real MCP client, no wallet
node test/live.mjs remote <url>   # same against a remote server

License

Proprietary, all rights reserved (see LICENSE). You may run the unmodified package to buy from Maxwell International's API. Copying, modifying, redistributing, or reusing any part of it with other services is not permitted without written permission. Permissions: [e-mail]