mcp-server-insumer

# mcp-server-insumer

[![npm](https://img.shields.io/npm/v/mcp-server-insumer)](https://www.npmjs.com/package/mcp-server-insumer) [![Glama](https://glama.ai/mcp/servers/insumerapi/mcp-server-insumer/badge)](https://glama.ai/mcp/servers/insumerapi/mcp-server-insumer) [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

MCP server for [InsumerAPI](https://insumermodel.com/developers/): condition-based access infrastructure. Send a wallet and conditions, get a signed boolean across 37 chains. No balances exposed, no identity required. Every result is signed and checkable offline against the published keys, and on EVM chains an optional Merkle proof lets the verifier check the balance against the block header without trusting the API.

Enables AI agents (Claude Desktop, Cursor, Windsurf, and any MCP-compatible client) to add condition-based access to any workflow — verify on-chain conditions, discover merchants, generate signed discount codes, and onboard new merchants.

**In production:** [AsterPay](https://github.com/AsterPay/erc8183-kya-hook) — a regulated payments stack — runs live ERC-8183 agentic-commerce trust scoring on InsumerAPI. [Case study](https://insumermodel.com/blog/asterpay-kya-erc8183-attestation-integration.html).

Also available as: [LangChain](https://pypi.org/project/langchain-insumer/) (26 tools, PyPI) | [ElizaOS](https://www.npmjs.com/package/@insumermodel/plugin-eliza) (10 actions, npm) | [OpenAI GPT](https://chatgpt.com/g/g-699c5e43ce2481918b3f1e7f144c8a49-insumerapi-verify) (GPT Store) | [insumer-verify](https://www.npmjs.com/package/insumer-verify) (client-side verification, npm)

**[Full AI Agent Verification API guide](https://insumermodel.com/ai-agent-verification-api/)**: covers all 37 chains, trust profiles, commerce protocols, and signature verification.

## Quick Start

### Claude Desktop

Add to your `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "insumer": {
      "command": "npx",
      "args": ["-y", "mcp-server-insumer"],
      "env": {
        "INSUMER_API_KEY": "insr_live_..."
      }
    }
  }
}
```

### Cursor / Windsurf

Add to your MCP settings:

```json
{
  "insumer": {
    "command": "npx",
    "args": ["-y", "mcp-server-insumer"],
    "env": {
      "INSUMER_API_KEY": "insr_live_..."
    }
  }
}
```

### Get a key — no signup, no dashboard, no password

Three paths, all give you a working `insr_live_...` key in seconds with 100 reads/day and 10 verification credits. One free key per email.

**Option A — Let your agent do it:** Start the server without a key. Your AI agent can call the `insumer_setup` tool with your email to generate a free key instantly. Add it to your config and restart.

**Option B — Terminal:**

```bash
curl -s -X POST https://api.insumermodel.com/v1/keys/create \
  -H "Content-Type: application/json" \
  -d '{"email": "you@example.com", "appName": "MCP Server", "tier": "free"}'
```

**Option C — Browser:** Enter your email on [insumermodel.com](https://insumermodel.com/?utm_source=npm-mcp-server-insumer) — the key appears inline.

Set it as `INSUMER_API_KEY` in your config.

**Already have a key?** Manage usage, top up, or upgrade at [insumermodel.com/developers/account/](https://insumermodel.com/developers/account/?utm_source=npm-mcp-server-insumer).

### Option D — Pay per call with x402 (no key at all)

Instead of a key, set `INSUMER_PAYMENT_KEY` to a **throwaway Base wallet** funded with a few dollars of USDC. Metered calls (`insumer_attest`, `insumer_wallet_trust`, `insumer_batch_wallet_trust`) are then paid inline via [x402](https://www.x402.org) — the server requests a price, signs an EIP-3009 USDC authorization on Base, and retries. No signup, no credits, no dashboard.

```json
{
  "mcpServers": {
    "insumer": {
      "command": "npx",
      "args": ["-y", "mcp-server-insumer"],
      "env": { "INSUMER_PAYMENT_KEY": "0x<throwaway-wallet-private-key>" }
    }
  }
}
```

- Base USDC only; the wallet needs USDC but **no ETH** (settlement is gasless).
- Each call spends a few cents (attest $0.05, trust $0.15). Use a **dedicated throwaway wallet** funded with a small amount — never a wallet holding meaningful funds.
- **Every quote is checked before the wallet signs.** The server pays only InsumerAPI's own receiving address (`0xAd982CB19aCCa2923Df8F687C0614a7700255a23`), only in USDC on Base, and never more than the cap: **$3.00 per call by default**, the price of the largest call today (a 10-wallet trust batch with Merkle proofs). Anything else is refused and nothing is signed. Set `INSUMER_MAX_PAYMENT_USDC` to change the cap, e.g. `"0.25"` if you only attest. The cheapest call is $0.05, so a cap below that refuses every paid call (the server warns at startup). A malformed value turns pay-per-call off rather than falling back to the default.
- If both `INSUMER_API_KEY` and `INSUMER_PAYMENT_KEY` are set, the key (credits) is used.

## Hosted endpoint (no install)

The same server runs at **`https://api.insumermodel.com/mcp`** over MCP streamable HTTP, for clients that connect by URL: ChatGPT plugins and developer-mode connectors, claude.ai custom connectors, and hosted agent platforms that cannot run an npm package. Paste the URL; there is nothing to configure.

It is shared and anonymous, so it serves the ten tools that make sense without a caller identity (`HOSTED_TOOLS`: signing keys, attest, compliance templates, wallet trust and batch trust, the merchant and token directories, the free discount check, code validation), and the metered tools share one free daily allowance. Past it, a call is refused with a pointer here. For your own allowance, key and credit management, or the merchant tools, run the package locally with your key as above.

To host the server yourself, build it and run `node build/http.js` with `INSUMER_API_KEY` set (`PORT`, `INSUMER_HOSTED_TOOLS` and `INSUMER_DAILY_CAP` are optional), or embed it: `createInsumerServer(options)` from the package root returns a configured server for any transport.

## What You Get Back

When your agent calls `insumer_attest`, you get an ECDSA-signed attestation:

```json
{
  "ok": true,
  "data": {
    "attestation": {
      "id": "ATST-A7C3E1B2D4F56789",
      "pass": true,
      "results": [
        {
          "condition": 0,
          "met": true,
          "label": "USDC >= 1000 on Ethereum",
          "type": "token_balance",
          "chainId": 1,
          "evaluatedCondition": {
            "chainId": 1,
            "contractAddress": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
            "operator": "gte",
            "threshold": "1000",
            "type": "token_balance"
          },
          "conditionHash": "0x8a3b...",
          "blockNumber": "0x1799043",
          "blockTimestamp": "2026-03-26T20:04:23.000Z"
        }
      ],
      "passCount": 1,
      "failCount": 0,
      "attestedAt": "2026-02-28T12:34:57.000Z",
      "expiresAt": "2026-02-28T13:04:57.000Z"
    },
    "sig": "NgA7BO8SAildiTrgIQY2UyXsBrySZknkP85pT2Zqv8Hq0KsCsB8DRFVMkXgnXtCXrbb726Is6k4LyyBYU+f/Pw==",
    "kid": "insumer-attest-v2",
    "pqSig": "<base64 ML-DSA-65 signature>",
    "pqKid": "insumer-attest-pq1"
  },
  "meta": {
    "version": "1.0",
    "timestamp": "2026-02-28T12:34:57.000Z",
    "creditsRemaining": 99,
    "creditsCharged": 1
  }
}
```

The `sig` is an ECDSA P-256 signature (base64, P1363 r||s, 88 characters). The `kid` identifies the key and selects the signed bytes: `insumer-attest-v2` signs `"insumer.attestation.v2\n" + canonical_json({v: 2, id, pass, results, attestedAt})` (keys sorted at every level); `insumer-attest-v1` signs the bare `JSON.stringify` of `{id, pass, results, attestedAt}` in insertion order. Since 2026-09-01 every attest and trust response also carries a post-quantum companion, `pqSig` and `pqKid` (ML-DSA-65 over the post-quantum domain tag plus the same classical preimage the `kid` selects), added beside `sig` and `kid` without changing them. The `conditionHash` is a SHA-256 of the exact condition logic that was evaluated.

No balances. No amounts. Just a cryptographically signed true/false.

For XRPL conditions, results include `ledgerIndex`, `ledgerHash` (validated ledger hash), and `trustLineState: { frozen: boolean }` instead of `blockNumber`/`blockTimestamp`. Native XRP conditions include `ledgerIndex` and `ledgerHash` but not `trustLineState`. Frozen trust lines cause `met: false`.

### Wallet Auth (JWT)

Add `format: "jwt"` to the `insumer_attest` tool parameters to receive the attestation as a standard JWT bearer token:

```json
{
  "wallet": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045",
  "conditions": [ ... ],
  "format": "jwt"
}
```

The response includes an additional `jwt` field containing an ES256-signed JWT, and beside it a `pqJwt` sibling (a compact JWS with `alg` ML-DSA-65 carrying the same claims, signed under `insumer-attest-pq1`). The `jwt` token is verifiable by any standard JWT library via the JWKS endpoint at `GET /v1/jwks` — making it compatible with Kong, Nginx, Cloudflare Access, AWS API Gateway, and other middleware that accepts JWT bearer tokens.

## Verify the Response

Your agent gets the attestation. Your application should verify it. Install [insumer-verify](https://www.npmjs.com/package/insumer-verify) (also on [PyPI](https://pypi.org/project/insumer-verify/) for Python: `pip install insumer-verify`, same checks, same 27 published test vectors):

```bash
npm install insumer-verify
```

```typescript
import { verifyAttestation } from "insumer-verify";

// attestationResponse = the full API envelope {ok, data: {attestation, sig, kid, pqSig, pqKid}, meta}
// Do NOT pass attestationResponse.data — the function expects the outer envelope
const result = await verifyAttestation(attestationResponse, {
  jwksUrl: "https://insumermodel.com/.well-known/jwks.json",
  maxAge: 120, // reject if block data is older than 2 minutes
});

if (result.valid) {
  // Signatu