mcp

# @invoket/mcp **One line to give your AI agent paid access to the [Invoket](https://api.invoket.com) APIs.** `@invoket/mcp` is a [Model Context Protocol](https://modelcontextprotocol.io) server that turns every paid Invoket endpoint into a typed MCP tool and pays for calls automatically over [x402](https://www.x402.org) — 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, and your host is notified of the change within the running session (`tools/listChanged`) — no package update, no restart. - **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](#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): ```json { "mcpServers": { "invoket": { "command": "npx", "args": ["-y", "@invoket/mcp"], "env": { "PAYER_PRIVATE_KEY": "0xYOUR_DEDICATED_WALLET_KEY", "MAX_PRICE_USD": "10.00", "SESSION_BUDGET_USD": "10.00" } } } } ``` Restart Claude Desktop. ### Claude Code ```bash claude mcp add invoket \ --env PAYER_PRIVATE_KEY=0xYOUR_DEDICATED_WALLET_KEY \ --env MAX_PRICE_USD=10.00 \ --env SESSION_BUDGET_USD=10.00 \ -- npx -y @invoket/mcp ``` ### Cursor Create `.cursor/mcp.json` in your project (or `~/.cursor/mcp.json` globally): ```json { "mcpServers": { "invoket": { "command": "npx", "args": ["-y", "@invoket/mcp"], "env": { "PAYER_PRIVATE_KEY": "0xYOUR_DEDICATED_WALLET_KEY", "MAX_PRICE_USD": "10.00", "SESSION_BUDGET_USD": "10.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: ```json { "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": "10.00", "SESSION_BUDGET_USD": "10.00" } } } } ``` ### OpenAI Codex CLI Add to `~/.codex/config.toml` (note the snake_case `mcp_servers`): ```toml [mcp_servers.invoket] command = "npx" args = ["-y", "@invoket/mcp"] env = { PAYER_PRIVATE_KEY = "0xYOUR_DEDICATED_WALLET_KEY", MAX_PRICE_USD = "10.00", SESSION_BUDGET_USD = "10.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: ```json { "mcpServers": { "invoket": { "command": "npx", "args": ["-y", "@invoket/mcp"], "env": { "PAYER_PRIVATE_KEY": "$INVOKET_PAYER_KEY", "MAX_PRICE_USD": "10.00", "SESSION_BUDGET_USD": "10.00" } } } } ``` ### Any other MCP host Any host that speaks MCP over **stdio** can launch: ```json { "command": "npx", "args": ["-y", "@invoket/mcp"], "env": { "PAYER_PRIVATE_KEY": "0xYOUR_DEDICATED_WALLET_KEY", "MAX_PRICE_USD": "10.00", "SESSION_BUDGET_USD": "10.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, the last discovery error (use it to diagnose an empty tool list), and any published entry that could not be turned into a tool, with the reason (`skippedCount` / `skipped[]`). 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` | `10.00` | Max price accepted for a single call, in USD. Any 402 challenge above it is refused before signing. The default clears the priciest call in the published catalog — `$2.505`, a 500-item batch; set it lower explicitly if you want a tighter bound. | | `SESSION_BUDGET_USD` | `10.00` | Total USD budget for the whole session (in-memory, per process). Same figure as the per-call cap: at worst one maximal call, or many small ones. | | `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. The tool list follows the gateway catalog with no package update: an endpoint added (or repriced, or retired) shows up at most `DISCOVERY_TTL_SECS` after the next tool call, and your host is notified (`tools/listChanged`) so it re-lists on the spot. Refreshes are lazy — an idle session makes no background traffic. | | `LOG_LEVEL` | `info` | Log verbosity on **stderr** only: `debug`, `info`, `warn`, `error`. | See [`.env.example`](./.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. **A newly published endpoint isn't in my tool list.** No package update is needed: the tools are generated from the gateway's discovery surfaces. The snapshot is refreshed lazily, so make one tool call (`platform_info` is free) once `DISCOVERY_TTL_SECS` has elapsed — the server then notifies your host that the list changed and the new tool appears. Hosts that ignore `tools/listChanged` pick it up on their next restart. If it still isn't there, call `platform_info` and read `skipped[]`: an endpoint the gateway publishes without an input schema, a price, or a description can't be turned into a usable tool, so it is skipped — the entry names it and gives the reason (`no_input_schema`, `no_price`, …). Nothing is guessed on your behalf; report it with `submit_review` and it gets fixed gateway-side. **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](./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](./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`](https://github.com/Invoket/mcp). ## License [MIT](./LICENSE) © Invoket