@invoket/mcp

One line to give your AI agent paid access to the Invoket APIs.

@invoket/mcp is a Model Context Protocol server that turns every paid Invoket endpoint into a typed MCP tool and pays for calls automatically over x402 — the agent never has to know the protocol. It runs on your machine over stdio, launched by your MCP host (Claude Desktop, Claude Code, Cursor, any MCP client). Invoket hosts nothing and never sees your key or your funds.

• Discovery-driven — tools are generated from the gateway's discovery surfaces. Nothing is hard-coded; endpoints added or removed on the gateway appear or disappear on their own.
• Non-custodial, BYOK — your payer key lives only in this process's environment, is used solely to sign locally, and never appears in any output. Unlike hosted x402 bridges or servers built on exchange API keys, there is no account, no API key, and no third party that can move your funds.
• Spend-capped — per-call and per-session ceilings, plus a check that the 402 challenge never exceeds the published price, refuse any overspend before signing.
• Free to explore — with no key it starts in discovery-only mode; the first call of the day to a trial-enabled endpoint is free.

---

Quickstart

You need Node.js ≥ 20. 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 — see Funding the payer wallet). To only browse the catalog and try free trial calls, you can skip the key entirely.

Use a dedicated, low-balance wallet. Your real exposure ceiling is that wallet's balance (on top of the spend caps below). Never point this at a primary wallet.

Every host below launches the same command; only the config file changes. Omit PAYER_PRIVATE_KEY anywhere to run in discovery-only mode.

Claude Desktop

Edit claude_desktop_config.json (Settings → Developer → Edit Config):

{
  "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"
      }
    }
  }
}

Restart Claude Desktop.

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

Cursor

Create .cursor/mcp.json in your project (or ~/.cursor/mcp.json globally):

{
  "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"
      }
    }
  }
}

A project-level .cursor/mcp.json lives inside your repo — make sure it (or your key) is gitignored, or prefer the global file.

Windsurf

Edit ~/.codeium/windsurf/mcp_config.json (same mcpServers shape as Cursor above), then reload the MCP servers from the Cascade panel.

VS Code (GitHub Copilot)

Create .vscode/mcp.json. VS Code can prompt for the key at startup instead of storing it in a file — recommended:

{
  "inputs": [
    {
      "id": "invoket-payer-key",
      "type": "promptString",
      "description": "Dedicated Invoket payer wallet private key (0x…)",
      "password": true
    }
  ],
  "servers": {
    "invoket": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@invoket/mcp"],
      "env": {
        "PAYER_PRIVATE_KEY": "${input:invoket-payer-key}",
        "MAX_PRICE_USD": "0.10",
        "SESSION_BUDGET_USD": "1.00"
      }
    }
  }
}

OpenAI Codex CLI

Add to ~/.codex/config.toml (note the snake_case mcp_servers):

[mcp_servers.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" }

Gemini CLI

Add to ~/.gemini/settings.json. $VAR values are resolved from your shell environment, so the key never has to be written into the file:

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

Any other MCP host

Any host that speaks MCP over stdio can launch:

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

---

Funding the payer wallet

Paid calls settle in USDC on Base (chain id 8453). To set up:

1. Create a fresh wallet used for nothing else and export its private key.
2. Send it a few dollars of USDC on the Base network (from an exchange that supports Base withdrawals, or bridged from another chain).
3. That's it — no ETH needed. Payments use signed EIP-3009 authorizations; the x402 facilitator submits the transaction and covers gas, your wallet only ever spends USDC.

Most endpoints cost $0.01 per call, and the price of every tool is stated in its description, so a couple of dollars goes a long way.

---

How a paid call works

When your agent invokes a paid tool, the server:

1. Calls the endpoint; the gateway answers 402 Payment Required with a signed challenge.
2. Checks the challenge against discovery: the amount must not exceed the published price, and must pass MAX_PRICE_USD and the remaining SESSION_BUDGET_USD. Any violation is refused before signing.
3. Signs the payment authorization locally (EIP-712 / EIP-3009) with your key and retries the call with the payment attached.
4. Reports the result to the agent with an explicit payment outcome.

The gateway only settles on success (its own rule: a 2xx means the call actually delivered), so you are not charged for upstream failures.

---

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.
• Free platform tools, always available (never charge):
  • 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).

Every tool result starts with an explicit payment outcome, so you always know whether a call cost anything:

• Paid — paid: true with the amount, network, and the settlement transaction hash, e.g. Paid $0.01 in USDC on eip155:8453 (tx 0x…).
• Trial — paid: false, trial: true: the gateway verified the payment authorization but did not settle it; the call was free.
• Not charged — paid: false for free calls and no-charge results.

Try it

Once connected, ask your agent things like:

"Use search_endpoints to find a tool that validates an IBAN, then check FR7630006000011234567890189."

"Call wallet_status — how much has this session spent and what are my caps?"

"What's the weather forecast for Paris this weekend?" (the agent finds and calls the matching paid tool on its own)

---

Environment variables

Variable	Default	Meaning
PAYER_PRIVATE_KEY	(none → discovery-only)	EVM private key of your dedicated, low-balance payer wallet. Used only to sign locally (EIP-712 / EIP-3009). Never transmitted, logged, or echoed. 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 (first call/day free). 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. No arbitrary URL is ever fetched.
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.

See .env.example for the annotated list.

---

Troubleshooting

The tool list is empty. Call platform_info: it reports the gateway origin, the number of discovered endpoints, and the last discovery error. Typical causes: no network, a proxy blocking api.invoket.com, or a custom INVOKET_BASE_URL that doesn't expose the discovery surfaces.

Every paid call is refused. Check wallet_status. If it reports discovery-only mode, PAYER_PRIVATE_KEY isn't reaching the process (some hosts require a full restart after editing config). If a cap is the reason, the error says which one — raise MAX_PRICE_USD / SESSION_BUDGET_USD deliberately, or start a new session to reset the in-memory session spend.

TRIAL_EXHAUSTED on a call I expected to be free. The free trial is one call per endpoint per day. Fund the wallet to keep going, or come back tomorrow. With a funded wallet the same call settles normally.

SETTLEMENT_FAILED on a paid call. The payment authorization was valid but on-chain settlement failed — most often an insufficient USDC balance on the payer wallet. You were not charged.

Timeouts on heavy endpoints. A few endpoints (large batches, cold caches) can take longer than most; the server-side default of HTTP_TIMEOUT_MS=30000 accommodates them. If you lowered it, raise it back.

Server won't start under npx. Check node --version ≥ 20, and look at stderr in your host's MCP logs — all diagnostics go there (never stdout, which carries the protocol).

---

FAQ

Where does my private key go? Nowhere. It is read from this process's environment, turned into a viem account in memory, and used only to produce EIP-712 signatures locally. It is never written to disk, never sent over the network, and a global scrubber redacts it from every log and error. The facilitator submits the signed transaction — the key itself never leaves your machine. See SECURITY.md.

What's the most it can spend? Bounded three ways, all enforced before signing: MAX_PRICE_USD per call, SESSION_BUDGET_USD per session, and a check that the 402 challenge amount never exceeds the price published by discovery. On top of that, your hard ceiling is the balance of the dedicated wallet you provide.

How do I test without paying? Run with no PAYER_PRIVATE_KEY to browse the catalog and read schemas in discovery-only mode. 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 chains / assets? USDC on Base in v1. The payment rail is selected from the gateway's 402 challenge; unsupported requirements are refused with a clear message.

How is this different from other x402 MCP servers? Two design choices: it is strictly non-custodial (a bare EVM key in your local environment — no hosted service, no exchange API keys, nothing that can custody or move funds beyond the signatures you cap), and it is fully discovery-driven (tools, schemas, and prices come from the gateway's published surfaces at runtime, so the server never lies about a price and never ships a stale, hard-coded tool list).

---

Security

This is a payer package: trust is the product. Read SECURITY.md for the full threat model, then audit the source — it's small and dependency-light on purpose. Publishing is done with npm provenance, linking each release tarball to its source commit on Invoket/mcp.

License

MIT © Invoket