Catalog MCP: Overview

​

How it fits: discover, then pay

​

The tool surface

​

Import the MCP

​

Environments

​

Instant Setup Commands

claude mcp add --transport http nevermined-catalog https://mcp.live.nevermined.app/mcp \
  --header "Authorization: Bearer ${NVM_API_KEY}"

mkdir -p ~/.cursor && echo '{
  "mcpServers": {
    "nevermined-catalog": {
      "url": "https://mcp.live.nevermined.app/mcp",
      "type": "http",
      "headers": { "Authorization": "Bearer YOUR_NEVERMINED_API_KEY" }
    }
  }
}' > ~/.cursor/mcp.json

// Add to ~/.continue/config.json
{
  "mcpServers": [
    {
      "name": "nevermined-catalog",
      "url": "https://mcp.live.nevermined.app/mcp",
      "transport": "http",
      "requestOptions": {
        "headers": { "Authorization": "Bearer YOUR_NEVERMINED_API_KEY" }
      }
    }
  ]
}

// Add to ~/Library/Application Support/Claude/claude_desktop_config.json
{
  "mcpServers": {
    "nevermined-catalog": {
      "url": "https://mcp.live.nevermined.app/mcp",
      "type": "http",
      "headers": { "Authorization": "Bearer YOUR_NEVERMINED_API_KEY" }
    }
  }
}

​

Auth & transport

• Transport: Streamable HTTP at POST /mcp (stateless — each call is a self-contained JSON-RPC request; no session id). Liveness at GET /health; readiness — which checks the Nevermined API is reachable — at GET /ready. initialize reports the server as nevermined-commerce.
• Two ways to authenticate, one server.
  • API key (any host that can send headers): put your Nevermined key on Authorization: Bearer <key>. Every tool is served exactly as before; this is the path the quickstart below uses.
  • OAuth (hosts that can’t be handed a key — Claude connectors, and hosts that follow the MCP authorization spec): connect with no header at all. The server is an OAuth 2.0 protected resource — when it needs a credential it answers 401 with a WWW-Authenticate challenge that points your host at the discovery document (/.well-known/oauth-protected-resource/mcp) and asks for the commerce scope. Your host follows it to Nevermined, you approve a spending cap once, and the host retries the call with the credential it was granted. The credential is a commerce grant: it spends only from the Delegation you approved, through the Router, and nothing else.
• Which hosts can be granted commerce. A host that follows the MCP spec identifies itself with a URL (its Client ID Metadata Document), so it never needs registering — but a commerce grant is account-level authority, and Nevermined grants it only to hosts its operator has listed by that URL. ChatGPT, Claude (the claude.ai connector) and Claude Code are listed out of the box, and a statically registered connector (LangSmith Fleet, with a registered redirect allow-list instead of a URL) is enabled the same way; a host that is neither is refused when you press Approve (BCK.OAUTH.0018), never silently granted. For a self-registering host the consent screen shows its domain (chatgpt.com) beside the name it calls itself, so you can check who is asking; a statically registered one shows its registered name only. How an operator lists another assistant: self-registering clients.
• The credential — key or grant — is forwarded to the Nevermined API per request, never stored, never logged. Never send it to the merchant you’re paying; it authenticates you to Nevermined, nothing else.

​

What happens without a credential

​

See it in action

​

Connect from your assistant

​

Pick an environment

​

What the consent page asks

• The spending cap, in USDC or EURC.
• How long the grant is valid for.
• Nothing else — the environment badge (Sandbox or Live) and who is asking are shown, not chosen. The assistant’s name appears with its origin beside it (chatgpt.com, claude.ai) for a self-registering client; a statically registered client such as LangSmith Fleet shows its name only.

• On Live, the cap is real money.
• The assistant may pay any service it can reach, not a fixed list.
• Nevermined’s routing fee comes out of the same cap — the cap is the total debited, not what merchants receive.
• Beyond spending, the grant lets the assistant read your Router payment history, your spend totals, and the funding wallet’s address and balance. The cap bounds what it can spend, not what it can see.

​

When the grant runs out

• The credential itself is short-lived (about an hour) and the assistant renews it silently with a refresh token for as long as the Delegation is usable and the assistant keeps using it: a grant left idle for 30 days can no longer be renewed silently (the renewal answers HTTP 400, BCK.OAUTH.0011) and has to be re-linked, even on a 90-day cap — the Delegation itself is untouched. You see nothing otherwise.
• When you disconnect, the credential is refused on its next use — a 401 on the paid call. What the assistant then shows you differs by product, verified on live 2026-09-24: Claude renders an inline Connect card and, once you grant, retries the blocked call by itself; ChatGPT shows a Reconnect Nevermined card with a button (its wording says the connection “expired” even when you revoked it); LangSmith Fleet reports “Authorization required” in the thread and names Integrations, but offers no button — and needs the extra step in the troubleshooting section below. On all three the connector itself stays configured; you never remove and re-add it. When the cap is spent or the validity window ends, the credential itself is still valid: the paid call fails with an error naming the exhausted or expired Delegation (an in-band tool error, not a re-link prompt), and the next renewal is refused with an HTTP 400 carrying BCK.OAUTH.0013 (budget exhausted) or BCK.OAUTH.0012 (delegation expired). Discovery keeps working in every case. Re-run the connect step to approve a new cap — a Delegation is never widened or extended in place.
• To revoke early, open Connections in the Nevermined app and disconnect the assistant. The credential stops working on its next call.

​

When connecting goes wrong

​

Quickstart

​

1. Connect your host

{
  "mcpServers": {
    "nevermined-catalog": {
      "url": "https://mcp.live.nevermined.app/mcp",
      "headers": { "Authorization": "Bearer ${NVM_API_KEY}" }
    }
  }
}

​

2. Get an API key

​

3. Run a discovery call

• list_categories — the Catalog’s categories, each with a count.
• search_services with { "query": "weather", "protocol": "x402" } — weather listings on the x402 rail, most relevant first. query is required; also filter by category and tag (both narrow the same tag set, so passing both matches a listing tagged with either), and set pageSize (1–100). You get the first page only: the pageToken in the result can’t be passed back yet, so narrow the query rather than paging. Each result is an ARD record carrying an identifier URN, not a slug — the slug is its last segment (urn:air:api.live.nevermined.app:service:openweather-mpp → openweather-mpp).
• get_service with { "slug": "<a-slug-from-the-search>" } — one service’s protocol, price label, and its requestShape: every callable endpoint with its path, HTTP method, price and pathParams, each carrying the exact payServiceArgs to hand to pay_service. An endpoint may also carry the JSON Schema of its request (requestSchema, as the merchant declares it — sanitised by Nevermined, not verified) or noParameters: true; for one with neither, build the request from its description or the provider’s docs. An endpoint with a quote has a live price: the merchant’s price for one call, on the rail and network the Router pays it on, with the routing fee excluded — see Price a call before paying.

​

4. Prepare to pay

​

Getting a Delegation from inside the chat

{
  "status": "human_action_required",
  "url": "https://embed.nevermined.app/cards/delegate?provider=crypto&network=live&sessionToken=…",
  "expiresAt": "2026-09-03T12:00:00.000Z",
  "instructions": "…"
}

{
  "status": "already_active",
  "delegationId": "121b880a-…",
  "budget": { "capCents": "500", "spentCents": "8", "remainingCents": "492", "currency": "usdc", "expiresAt": "2026-09-23T13:29:31.691Z" },
  "source": "oauth_grant",
  "message": "Your spending budget is in place: delegation 121b880a… — cap 5.00 USDC, 0.08 USDC spent, 4.92 USDC remaining, valid until 2026-09-23T13:29:31.691Z. …",
  "instructions": "No human action is needed now. Call pay_service; it spends from this budget by default."
}

​

5. Make a paid call

{
  "slug": "dexter-x402",
  "path": "/quote",
  "body": { "pair": "ETH/USDC" }
}

{
  "paid": true,
  "upstreamStatus": 200,
  "priceLabel": "$0.02",
  "payment": { "paymentId": "b1f9c2e4-…", "txHash": "0xfc8af37b…" },
  "request": { "method": "POST", "path": "/quote", "methodSource": "catalog", "catalogEndpoint": "/quote" },
  "response": { "…": "the vendor's body, unchanged" }
}

​

6. Check your spend and your balance

• list_payments — your Router payments, newest first, across every protocol. Filter by delegationId, from, to.
• payment_summary — a count of payments plus a daily time series. (For what you’ve spent, use get_budget; for per-payment amounts, list_payments.)
• get_budget — the spending budget pay_service draws on: cap, spent, remaining, and expiry. Relay its message verbatim.
• wallet_balance — what your personal wallet actually holds. Different question: the ledger says what you’ve spent, the budget says what you’re allowed to spend, but the crypto rails pull from your wallet and only this says whether the money is there. Read the network the merchant quoted, not the one with money in it — live settles on two chains (USDC on Base 8453, USDC.e on Tempo 4217) and most services accept only one.

​

When a payment is refused

​

Price a call before paying

{ "slug": "dexter-x402", "path": "/quote", "body": { "pair": "ETH/USDC" } }

{
  "paymentRequired": true,
  "upstreamStatus": 402,
  "optionSet": "delegation",
  "delegationId": "121b880a-…",
  "quoteId": "qt_8f2a…",
  "expiresAt": "2026-10-02T14:05:00.000Z",
  "protocol": "x402",
  "settlement": { "recipient": "0x2096…", "amount": "20000", "asset": "USDC", "network": "base", "approxCents": "2" },
  "fee": { "bps": 200, "capChargedCents": "3", "capChargedMicros": "20400" },
  "nextTool": "pay_service",
  "instructions": "Nothing was charged. `fee.capChargedCents` is the fee-inclusive total this call would cost."
}

{ "slug": "dexter-x402", "path": "/quote", "body": { "pair": "ETH/USDC" }, "delegationId": "121b880a-…", "quoteId": "qt_8f2a…", "maxTotalCents": 3 }

​

Let the platform pick a service

​

Which tool to reach for

​

Result and error conventions

• One JSON object per call. Each tool returns a single JSON object as the MCP text content.
• Refusals are legible results, not exceptions — an object carrying an error (and often a code and retryable), so an agent can branch on it.
• Missing or rejected credential → 401 with a WWW-Authenticate challenge (error="invalid_token" when refused). A host that links per tool gets the challenge in-band under _meta["mcp/www_authenticate"].
• Money is in cents. capCents is whole cents; spentCents / remainingCents carry up to four decimals (charged per call at 1/10,000 of a cent). The routing fee is included — never re-derive a figure by summing your own calls. Payment amounts in list_payments are in the asset’s smallest unit (assetDecimals), not cents.
• Error codes. Router refusals carry BCK.ROUTER.* (Router guardrails); OAuth refusals carry BCK.OAUTH.*. Full catalogue: API error reference.

​

Not this MCP

​

Next