Catalog MCP

The Catalog MCP is a hosted MCP server that drops the Nevermined Catalog and Router straight into the tools an AI assistant already has. Point any MCP host — Claude Desktop, Cursor, a generic MCP client — at it, and your agent can discover paid services in the Nevermined Catalog and pay for them through the Router, all from a budget you cap. It’s the third way to reach the Catalog + Router capability, alongside the public REST API and the webapp — and the one that needs no code. The server holds no funds and stores no state: every payment draws on the caller’s own spend-capped Delegation, using the caller’s own Nevermined API key, forwarded per request and never stored.

This is the buyer side, packaged as MCP tools. If you instead want to put a paywall on your own MCP server so its tools get paid, that’s the seller side — see MCP Integration. See Not this MCP below to be sure you’re on the right page.

How it fits: discover, then pay

The Catalog MCP is the same two-step motion the rest of the Catalog documents, exposed as tools:

Discover

list_categories, search_services, and get_service read the Catalog — public, no key. Your agent finds a service and reads its protocol, endpoint, and price.

Pay

pay_service hands the call to the Router, which reads the merchant’s 402, pays it from your Delegation, enforces the cap, and relays the vendor’s response.

Your agent never holds a private key, never learns a payment protocol, and never needs an account with the service it just paid. The Router, not the agent, speaks each rail — see How the Router works.

The tool surface

Seven tools. Discovery is free — no credential needed. Paying and reading your ledger are paid tools: they need a credential, either your API key or an OAuth grant your host obtains for you.

Tool	Auth	What it does
`list_categories`	free	Catalog categories, with a count each.
`search_services`	free	Search listings. Filters (all optional): `query`, `category`, `protocol`, `tag`, `page`, `offset`.
`get_service`	free	One service by `slug` — protocol, endpoint, price label, discovery links.
`pay_service`	paid	Pay for a service and return the vendor’s response. Charges real funds.
`setup_delegation`	paid	Start the delegation ceremony — returns one URL a human opens to authorise a spending cap.
`list_payments`	paid	Your Router payments (unified ledger, newest first). Filters: `delegationId`, `from`, `to`.
`payment_summary`	paid	Total spend plus a time series. Filters: `from`, `to`.

Every tool declares this split in its listing (securitySchemes: noauth on the free tools, oauth2 with the commerce scope on the paid ones), so a host that reads tool metadata — ChatGPT does — knows which tools need linking before it calls one.

Auth & transport

Transport: Streamable HTTP at POST /mcp (stateless). Liveness at GET /health; readiness — which checks the Nevermined API is reachable — at GET /ready.
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.
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

The server runs on two hostnames per environment. They serve the same tools and differ only in when a request without a credential gets the challenge:

Host	`initialize`, `tools/list`, free tools	A paid tool call	With a credential
`mcp.<env>.nevermined.app` — the URL in the quickstart	Served, no credential needed	`401` + challenge — your host prompts you to connect, then retries	Served
`mcp.api.<env>.nevermined.app`	`401` + challenge on the very first request	`401` + challenge	Served

Use the first host. It lets an assistant browse the Catalog before anyone signs in, and starts the consent only when the agent actually tries to pay — Claude shows an inline Connect card at that moment and retries the same call once you’ve approved. The second host is for clients that only look for auth when they first connect; it challenges immediately instead. An expired or revoked credential on a paid call also comes back as a 401 (error="invalid_token"), so a host can refresh or re-authorize on its own rather than surfacing an error to you. A host that links accounts per tool rather than per connection (ChatGPT’s documented mechanism) gets the same information in-band: the paid tools carry securitySchemes, and a refused call returns an error result carrying the challenge under _meta["mcp/www_authenticate"].

Environments are sandbox and live — mcp.sandbox.nevermined.app and mcp.live.nevermined.app. The OAuth ceremony lands you on the same consent screen for both; on live the cap you approve is real money.

Quickstart

Connect a host, run a discovery call, then a paid call — end to end. Discovery works with no credentials; paying needs a Nevermined API key and a funded, spend-capped Delegation.

1. Connect your host

Point an MCP client at the server URL and set the Authorization header to your Nevermined API key. Any host that supports remote (HTTP) MCP servers with headers takes this shape (a host that runs OAuth for you — Claude connectors, for instance — takes just the URL, no header, and prompts you to connect the first time the agent tries to pay):

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

Environment	Server URL	Purpose
Live	`https://mcp.live.nevermined.app/mcp`	Discovery and real payments

The config above points at live, where pay_service moves real funds to a real merchant. The Catalog is Live-only for payment — the sandbox Router funds testnets only, so no listed service is payable there. Rehearse with the cheapest sub-cent service and keep your first Delegation cap small.

Stdio-only host? Some hosts speak MCP over stdio, not HTTP. Bridge them with mcp-remote, which forwards the same URL and header to a local stdio endpoint.

2. Get an API key

Create a Nevermined API key from the Nevermined app. Discovery tools don’t need it, but pay_service and the ledger tools do. Older keys are rejected by the Router — see the Router quickstart for how to tell which you have. The key is sent as a request header, forwarded to the Nevermined API per call, and never stored or logged by the MCP server. Never put it in a tool argument or send it to a merchant.

3. Run a discovery call

Discovery is public — call these before you’ve set any key. Ask your host to run:

list_categories — the Catalog’s categories, each with a count.
search_services with { "protocol": "x402" } — listings on the x402 rail. Also filter by query, category, tag, and page with page / offset.
get_service with { "slug": "<a-slug-from-the-search>" } — one service’s protocol, endpoint, and price label.

In natural language that’s just: “List the Nevermined categories, then find x402 services for weather.” The host picks the tools.

4. Prepare to pay

pay_service moves real money, so it needs a funded budget on your account:

Create a Delegation

A hard cap and an expiry. Created once and reused. See Create a Delegation.Or let the agent ask for one. Calling setup_delegation returns a single URL for you to open; you set the currency, cap, duration and transaction limit in the browser, and the agent carries on. The agent cannot choose those numbers — that is the point of a mandate. See Getting a Delegation from inside the chat.

Fund its wallet

Both rails pull from your own wallet, so it must hold the payment asset on the network you’ll pay on. See Fund your wallet.

pay_service uses the accessible Delegation (Active, unexpired, funded) automatically. Pass an explicit delegationId only to override that choice.

Getting a Delegation from inside the chat

If your agent reaches a paid call with no Delegation, pay_service returns { "error": "no_delegation", "nextTool": "setup_delegation" } instead of stopping. Calling setup_delegation answers with one URL:

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

Open it, set your limits, and tell the agent to try again — pay_service picks the new Delegation up on its next call. Nothing needs to redirect back to the agent, and in a chat host nothing can: the page simply confirms and you close the tab.

The url carries a short-lived session token bound to your account. Treat it like a credential — it is for you, not for sharing.

If your host can receive a redirect — a CLI listening on http://127.0.0.1:<port>/… — pass it as returnUrl and your browser returns there with the delegationId. Any other origin has to be allow-listed on the deployment first; one that isn’t comes back as { "error": "return_url_not_allowed" } before you open a browser, rather than failing after you’ve filled in the form. If a usable Delegation already exists, the tool answers { "status": "already_active", "delegationId": "…" } and nobody is interrupted.

5. Make a paid call

Call pay_service with the service slug and the request you want made — path, method, body, and headers as the vendor needs them. If you omit method, the tool uses the catalog method for the matching endpoint, falling back to POST. For a slug-routed GET, put the query string without ? in search, separate from path. Optional maxTotalCents is a non-negative safe integer that caps this call’s fee-inclusive, whole-cent budget reserve; the Delegation cap still limits total spend.

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

The server resolves the slug, confirms it’s payable, pays the vendor’s 402 from your Delegation, and relays the vendor’s own response:

{
  "paid": true,
  "upstreamStatus": 200,
  "payment": { "paymentId": "b1f9c2e4-…", "txHash": "0xfc8af37b…" },
  "response": { "…": "the vendor's body, unchanged" }
}

If the service isn’t on a payable rail (only x402 / MPP listings are), nothing is charged — you get a signpost to its native endpoint instead:

{ "payable": false, "protocol": "rest", "nativeEndpoint": "https://…" }

Retries are deduped, not double-charged. The requestId is derived from your key plus the full request, so a host that retries the same call hits the Router’s idempotency guard and gets { "status": "already_paid", "paymentId": "…" } back — the original payment, not a second one. Pass an explicit requestId only when you want to buy again.

6. Check what you spent

list_payments — your Router payments, newest first, across every protocol. Filter by delegationId, from, to.
payment_summary — total spend plus a time series over an optional from / to window.

Both read the same unified ledger the Router ledger page documents, so a payment made here is reconcilable with everything else your agents spend.

When a payment is refused

Refusals come back as legible results, not exceptions. The ones to recognize:

Result	What happened
HTTP `401` with a `WWW-Authenticate` challenge	A paid tool was called with no credential, or with one Nevermined refused (`error="invalid_token"`). An OAuth-capable host handles this itself — connect (or reconnect) when it asks. A headers-only host can’t: set your API key (step 2).
`{ "error": "authentication_required" }`	The same refusal, in-band — you’ll only see it on a self-hosted instance that has no OAuth surface configured. Set your API key (step 2).
`{ "error": "payment_failed", "code": "BCK.ROUTER.0003", … }`	The spend would exceed your Delegation cap, or it expired. Widening the cap in response is almost always the wrong move — see Guardrails.
`{ "status": "already_paid", "paymentId": "…" }`	A retry was deduped. Not a failure — you weren’t charged twice.
`{ "error": "payment_indeterminate", … }`	The connection dropped mid-payment. Check `list_payments` before retrying.
`{ "error": "no_delegation", "nextTool": "setup_delegation" }`	No Delegation on the account yet. Call `setup_delegation` and open the URL it returns — see step 4.

Not this MCP

Nevermined ships three MCP servers. Make sure you want this one:

MCP	Side	What it’s for
Catalog MCP (this page)	Buyer	Your agent discovers & pays for Catalog services. You provide just an API key and a funded budget.
MCP Integration	Seller	Put a paywall on your own MCP server with the Payments Library (`withPaywall`), so your tools get paid.
Docs MCP	—	Streams the Nevermined documentation into your IDE so an assistant can vibe-code an integration. It sells nothing.

Using the Catalog from a harness

The code-free playbook for driving discovery and payment from your agent — wiring the MCP in is Step 3.

Catalog: discover

What’s listed, how filtering works, and what “payable” means.

Router: pay

Delegations, the spending cap, the rails, and every refusal code.

Router guardrails

What the Router enforces, what it refuses, and why widening a cap is the wrong reflex.

Payment ledger

Read back everything your agents have spent, across every protocol.

Learn

Build

Payments

Nevermined Catalog

Solutions

Organizations

Integrations

Payment Patterns

Components

Specs

How it fits: discover, then pay

Discover

Pay

The tool surface

Auth & transport

What happens without a credential

Quickstart

1. Connect your host

2. Get an API key

3. Run a discovery call

4. Prepare to pay

Getting a Delegation from inside the chat

5. Make a paid call

6. Check what you spent

When a payment is refused

Not this MCP

Next

Using the Catalog from a harness

Catalog: discover

Router: pay

Router guardrails

Payment ledger

​How it fits: discover, then pay

Discover

Pay

​The tool surface

​Auth & transport

​What happens without a credential

​Quickstart

​1. Connect your host

​2. Get an API key

​3. Run a discovery call

​4. Prepare to pay

​Getting a Delegation from inside the chat

​5. Make a paid call

​6. Check what you spent

​When a payment is refused

​Not this MCP

​Next

Using the Catalog from a harness

Catalog: discover

Router: pay

Router guardrails

Payment ledger

How it fits: discover, then pay

The tool surface

Auth & transport

What happens without a credential

Quickstart

1. Connect your host

2. Get an API key

3. Run a discovery call

4. Prepare to pay

Getting a Delegation from inside the chat

5. Make a paid call

6. Check what you spent

When a payment is refused

Not this MCP

Next