The Invoket MCP server

@invoket/mcp is the least-friction way to give an AI agent paid access to Invoket: one line of MCP host config and every paid endpoint becomes a typed tool your agent can call. It pays for calls automatically over x402 — the agent never has to know the protocol.

The server runs on your machine over stdio, launched by your MCP host (Claude Desktop, Claude Code, any MCP client). Invoket hosts nothing and never sees your key or your funds. The tools are generated live from the gateway’s discovery surfaces — nothing is hard-coded, so endpoints added or removed on the gateway appear or disappear on their own.

If you are wiring the raw x402 flow yourself instead of going through MCP, see For agents and the Quickstart.

Who it is for

Anyone operating an agent that should be able to act — pay, message, advise, plan, buy — and needs the pre-action checks Invoket serves. If your runtime speaks MCP (Claude Desktop, Claude Code, an SDK agent, any MCP host), this is the path with the least code between your agent and a paid call.

Security first — non-custodial BYOK

This is a payer package, so trust is the product. Every guarantee below is enforced by the package itself; read the full threat model in SECURITY.md and audit the source — it is small and dependency-light on purpose.

Your key never leaves your machine. PAYER_PRIVATE_KEY is read once from the process environment and used only to produce EIP-712 / EIP-3009 signatures locally. It is never transmitted, never written to disk, never returned in a tool result, and never logged — a global output scrubber redacts key-shaped material from every log line and error as a backstop.
Spending is bounded before any signature. Three independent checks run before a payment is signed, and any breach is a hard refusal: MAX_PRICE_USD (per-call ceiling), SESSION_BUDGET_USD (per-session budget, in memory), and a check that the 402 challenge amount never exceeds the price published by discovery — the gateway cannot quietly overcharge.
Single origin, no arbitrary fetch. Every request goes to the one configured origin (INVOKET_BASE_URL, HTTPS enforced except on localhost). No model-driven input can make the server fetch another URL.
No persistent state, no telemetry. Nothing is written to disk; spend counters live in memory for the session only.

Use a dedicated, low-balance wallet. The spend caps bound per-call and per-session cost, but your hard exposure ceiling is simply the balance of the wallet whose key you provide. Never point this at a primary or high-value wallet.

Quickstart

You need Node.js ≥ 20. There is no install step — your MCP host runs npx -y @invoket/mcp. To make paid calls you also need a funded EVM wallet (USDC on Base). To only browse the catalog and try free trial calls, omit the key entirely and the server starts in discovery-only mode.

Claude Desktop

Edit claude_desktop_config.json (Settings → Developer → Edit Config), then restart Claude Desktop:

{
  "mcpServers": {
    "invoket": {
      "command": "npx",
      "args": ["-y", "@invoket/mcp"],
      "env": {
        "PAYER_PRIVATE_KEY": "0xYOUR_DEDICATED_WALLET_KEY",
        "MAX_PRICE_USD": "0.10",
        "SESSION_BUDGET_USD": "1.00"
      }
    }
  }
}

Claude Code

claude mcp add invoket \
  --env PAYER_PRIVATE_KEY=0xYOUR_DEDICATED_WALLET_KEY \
  --env MAX_PRICE_USD=0.10 \
  --env SESSION_BUDGET_USD=1.00 \
  -- npx -y @invoket/mcp

Any MCP host

Any host that speaks MCP over stdio can launch the same command:

{
  "command": "npx",
  "args": ["-y", "@invoket/mcp"],
  "env": {
    "PAYER_PRIVATE_KEY": "0xYOUR_DEDICATED_WALLET_KEY",
    "MAX_PRICE_USD": "0.10",
    "SESSION_BUDGET_USD": "1.00"
  }
}

Omit PAYER_PRIVATE_KEY to run in discovery-only mode.

Environment variables

The two you will usually set are PAYER_PRIVATE_KEY (your dedicated wallet) and the spend caps. The rest have safe defaults.

Variable	Default	Meaning
`PAYER_PRIVATE_KEY`	(none → discovery-only)	EVM private key of your dedicated, low-balance payer wallet. Signs locally only; never transmitted or logged. Without it, paid calls are disabled.
`MAX_PRICE_USD`	`0.10`	Max price accepted for a single call, in USD. Any 402 challenge above it is refused before signing.
`SESSION_BUDGET_USD`	`1.00`	Total USD budget for the whole session (in-memory, per process).
`PREFER_TRIAL`	`true`	Select the free trial requirement when the gateway offers it. Set `false` to always settle on the paid rail.
`INVOKET_BASE_URL`	`https://api.invoket.com`	The single origin every tool calls. HTTPS required except on localhost.
`HTTP_TIMEOUT_MS`	`30000`	HTTP request timeout to the gateway, in milliseconds.
`DISCOVERY_TTL_SECS`	`300`	How long a discovery snapshot is reused before a lazy refresh.
`LOG_LEVEL`	`info`	Log verbosity on stderr only: `debug`, `info`, `warn`, `error`.

What your agent sees

One typed tool per paid endpoint, generated from discovery: the name is derived from the path, the input schema from the endpoint’s published schema, and the price is stated in the description. When a call carries no payment (a trial or free call), the result reports paid: false — your agent always knows whether a call cost anything.
Free platform tools, always available and never charged:
- search_endpoints — full-text search over the discovered catalog; go from an intent to the right paid tool.
- wallet_status — payment mode, payer public address, configured caps and session spend (never the private key, never an on-chain balance).
- submit_review — send feedback (a gap, a bug, a pricing concern) to Invoket.
- platform_info — gateway origin, number of discovered endpoints, snapshot freshness and the last discovery error (use it to diagnose an empty tool list).

Free trial

With no key, the server runs in discovery-only mode: browse the catalog and read schemas without paying. With a key, the first call each day to a trial-enabled endpoint is free (PREFER_TRIAL defaults to true) and reports paid: false. Which endpoints currently offer a trial is driven by the gateway’s /catalog, never hard-coded.

Chains and assets

USDC on Base in v1. The payment rail is selected from the gateway’s 402 challenge; an unsupported requirement is refused with a clear message.