Using the Catalog from a harness

A short, reusable manifesto for anyone driving the Nevermined Catalog from an agent harness — Claude Code, Cursor, an MCP client, or your own runtime. No code — just the flow, the principles, and the links.

This page is meant to be handed to your agent as-is. Point your harness at it (or share the link) and it has everything it needs to discover, pay, and reconcile safely.

See it in action

New here? Watch the Song from the Headlines example drive the whole flow from a harness, end to end — then read on for the machine-readable version your agent follows (the video is the one part of this page a harness can’t consume).

Song from the Headlines — a Catalog use case driven from a harness.

What the Catalog is

The Nevermined Catalog is a curated directory of external AI services your agent can pay for per call — no per-vendor signup, no subscriptions. Each service settles a single request through Nevermined using the x402 or MPP payment protocols. Your agent discovers a service, calls it, and the payment happens in the background against a budget you control.

Browse services: nevermined.app/catalog
Machine-readable feed of every service: ai-catalog.json
What “agentic commerce” means: nevermined.ai/glossary/agentic-commerce

The mental model

Five pieces, and it clicks:

Piece	What it is
Harness	your agent runtime — where the agent decides what to buy
Catalog	the marketplace of pay-per-call services
Router / Facilitator	Nevermined’s broker that reads a service’s payment challenge, pays it, and returns the result — so your agent never touches a vendor account or a private key
Delegation	your spending authority: a hard, time-boxed budget cap the agent pays within
API key	authenticates your agent to Nevermined on every call — an assistant host that runs OAuth (Claude, ChatGPT, LangSmith Fleet) obtains one for you through the commerce consent, so your agent never handles it

The agent never holds card numbers or wallet keys and never calls Stripe or a chain directly. It holds an API key and a delegation; Nevermined does the rest.

Step 0 — One-time setup (a human is needed once)

The Catalog is Live-only for payment. Discovery works on either host, but listed services settle on mainnet and the sandbox Router funds testnets only — so paying one from sandbox fails (400 BCK.ROUTER.0001). The only things a sandbox key can buy are the two free testnet test merchants kept there for rehearsal (see the Commerce MCP page). Every step here uses the Live network and real (if tiny) money; keep caps small and rehearse with a sub-cent service.

App (sign in, keys, delegations): nevermined.app
Live API base: https://api.live.nevermined.app — your API key for this network is prefixed live: (send the whole string, prefix included).

Sign in and get a key. Open nevermined.app, sign in, and get a Nevermined API Key — a one-time, human-in-the-loop step (SDK-minted, the embedded /auth/cli login, or the device flow (RFC 8628) for headless agents). See Get a Nevermined API key for the embedded-login and SDK paths, and Authentication for the OAuth ones. Store it, reuse it, and keep it out of logs.

The agent-facing version of this step is auth.md — the machine-readable manifest kept in lockstep with the API: the discovery documents, the bearer contract and key format, every ceremony that ends in a key (SDK, device flow, and the OAuth commerce consent), and what needs a human. Hand it to your harness alongside this page; where the two differ, auth.md is the one that names endpoints that exist today.

Or let your assistant get it for you. If your harness is an AI assistant that runs OAuth on your behalf — Claude (the claude.ai connector), ChatGPT, Claude Code, LangSmith Fleet, or another MCP host whose client Nevermined’s operator has listed (following the MCP authorization spec buys a host its identity, not this authority — an unlisted host is refused at the consent screen) — you skip the key, and Step 1’s delegation: add the Catalog MCP with no key, and the assistant sends you to Nevermined to approve a spending cap once — when you add the server on the strict host, on the first paid call on the public one. That approval is the delegation of Step 1 and the credential of this step, in one screen; the assistant renews the credential silently. The cap bounds what it can spend — not what the grant can see or do on your account (it reads your Router payment history and wallet balance, lists and can revoke your delegations, and can start a new delegation ceremony for you to approve); auth.md §6 has the full list. Which host and client each assistant uses (two of the four above need the strict mcp.api.<tier> host), and the mechanics the host follows, are auth.md §6. Funding is not skipped: a commerce grant spends stablecoin from your own wallet, so the next bullet still applies. Fund a way to pay. A stablecoin method exists by default — fund it on the networks the Catalog settles on: Base and Tempo. Services settle on different rails (some on Base, some on Tempo), so keeping a small balance on both keeps any service payable — otherwise a call can fail simply because your funds are on the other network. To pay by card instead, enroll one once (a one-time in-browser step) — card enrolment funds the card rails only; a commerce grant from an assistant always spends stablecoin from your own wallet.

Step 1 — Set a budget you cannot exceed (the delegation)

The delegation is your capped, server-enforced spending authority (see the mental model above) — the single most important safety control here.

Create or reuse one in the app (Payment Methods → Delegate) or programmatically; reuse any delegation whose status is Active.
Set the cap to the most you’re willing to spend on the whole task (e.g. $1), and keep a soft stop a little below it in your agent so a run halts cleanly rather than erroring at the wall.

Step 2 — Discover services (free, no key required)

The catalog’s read surface is public — browse or filter it before spending a cent.

Human view: nevermined.app/catalog
Full feed (all services): ai-catalog.json

Every listing tells you what you need to choose: its slug (how you address it), protocol (x402 or MPP — handled for you), a price label, its endpoints, and tags/category. Filter by task (e.g. web search, email enrichment, scraping, social data) and by price, and shortlist the cheapest service that answers the need. Listings are returned in a recommended order — Nevermined’s own quality ranking, not alphabetical — so the top of the list is a sensible default rather than something you score yourself. Treat that order as guidance, not a contract: it is recomputed as health and traction change. Each feed entry also carries a displayPriceSource of settled or quoted (a settled price means real, multi-payer settlement — the service is genuinely used, not just advertised) and partner/featured flags you can weigh.

Build the request body from the listing, not from guesswork. Each endpoint publishes a requestExample and responseFields in its Catalog detail — copy the example and change the values. In particular, multi-model services expect a provider-prefixed model id (e.g. openai/gpt-4o-mini, google/gemini-2.5-flash-lite); a bare gpt-4o-mini is usually rejected with a typed 400. Read the exact id from the requestExample rather than probing paid calls.

Don’t know which service to pay? Let the Router pick instead of scoring listings yourself: POST /api/v1/router/select with a plain-language intent (and optional filters — category, protocol, network, maxPriceLabel) returns the single best payable service plus a ranked shortlist, chosen deterministically on Nevermined’s own relevance and quality signals behind a payability gate. Take the returned order as authoritative — read the order, not the numbers: the relevance scores can sit on different scales (semantic vs keyword), so re-sorting by them yourself can pick worse. Add autoPay: true (with requestId + delegationId) to select and pay in one call. This uses your API key — see the Router quickstart, and Let the platform pick a service for the full shortlist shape.

Step 3 — Connect the harness to the Catalog

Two paths — pick one:

	Catalog MCP	Router API
Best for	harnesses that speak MCP	any harness / quick start
How	add the Nevermined Catalog MCP server to your harness config with your API key — or, in an assistant that runs OAuth (Claude, ChatGPT, Fleet), by URL alone and approve a spending cap on the first paid call; you get discovery + payment tools natively	call Nevermined’s Router to pay any service by its slug
Note	most harnesses load MCP servers at startup — add it, then restart the session	works immediately, no restart
Docs	Catalog MCP	Router quickstart · OpenAPI

Either way the shape is the same: name the service (by slug), pass your delegation, get the result back. The Router reads the vendor’s payment challenge, pays from your delegation, and returns the response.

Using the Catalog MCP

If your harness speaks MCP, the server drops discovery and payment in as native tools. Point your client at the server URL and put your Nevermined API key on the Authorization header — or, in an assistant that runs OAuth (Claude, ChatGPT, LangSmith Fleet), connect by URL alone and approve a spending cap once:

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

Use https://mcp.sandbox.nevermined.app/mcp to rehearse. The tools your agent then has — discovery is free, the rest need the credential, and only pay_service / route_by_intent (with autoPay) move money:

Tool	Free?	What it does
`list_categories` · `search_services` · `get_service`	free	Browse the Catalog, search it (hybrid ranking), and read one service’s callable endpoints.
`route_by_intent`	paid	Describe a need; get the single best payable service back, and optionally pay it.
`quote_service`	paid	Price one call before paying — live, fee-inclusive total.
`pay_service`	paid	Pay a service and return its response.
`setup_delegation`	paid	Get a URL for a human to approve a spending cap, when none exists yet.
`get_payment_result`	paid	Read a paid call’s result by `paymentId` (for a `pending` call, or a lost response).
`list_payments` · `payment_summary` · `get_budget` · `wallet_balance`	paid	Reconcile spend, count payments, read the budget, and check wallet funding.

Every argument, return field and refusal is in the Catalog MCP reference; the product page has the per-assistant setup walkthroughs.

The calling convention (one canonical shape)

If you drive the Router API directly, there is one convention in three forms — all settle identically; they differ only in how you pass the target and where the result comes back. Pick the one that fits your client. Full copy-paste curl lives in the Router quickstart; this is the map.

Form	Endpoint	How you name the service	Best for
JSON	`POST /api/v1/router/route`	`url` (off-catalog) or `slug` (cataloged) in the JSON body — exactly one	most harnesses (the quickstart uses `url`)
Header proxy	`ANY /api/v1/router/proxy`	`X-Router-Target-Slug` header (cataloged) or `X-Router-Target-Url` (off-catalog) — exactly one	pointing an existing HTTP client at the Router transparently
Path	`ANY /api/v1/router/svc/<slug>[/<subpath>]`	the slug in the path	a REST-shaped call that maps cleanly onto the service’s sub-paths

All three forms need the same two facts — which delegation pays and an idempotency id — but they carry them differently. The JSON form (/router/route) takes them as body fields: delegationId and requestId (both required — a header-only /route call fails validation), and returns the payment in the JSON response envelope (payment.paymentId, payment.status, payment.txHash, payment.failureReason). The two transparent forms (/router/proxy, /router/svc) carry them as X-Router-* request headers instead, and return the payment as response headers:

Header	Required	Meaning
`X-Router-Delegation-Id`	yes	which delegation (budget) pays
`X-Router-Request-Id`	yes	your idempotency id — reuse it on a retry so a hiccup never double-charges (a duplicate is refused with `409 BCK.ROUTER.0002`, the original `paymentId` in `params`); use a fresh one per new purchase, and per async poll (see below)
`X-Router-Upstream-Authorization`	no	the agent’s own auth to the upstream, if it needs one
`X-Router-Forward-<name>`	no	forward one extra header to the upstream

The transparent response carries X-Router-Payment-Id, X-Router-Payment-Status, X-Router-Tx-Hash, and — on a failed/unsettled payment — X-Router-Failure-Reason.

Address a cataloged service by its slug, never a raw URL: the Router hides the vendor’s host on purpose, so paying one by raw URL is refused (409 BCK.ROUTER.0014). Keep raw URLs and hosts out of the path — a security guard blocks anything there that looks like it changes the destination host. The resolved slug in /svc/<slug> is exempt, because the Router maps it to the host server-side.

Async services (generate, then poll)

Some services are asynchronous — media generation, for example. The first call returns a taskId instead of the result, and you poll a status endpoint until the result appears. It is fully supported; keep these in mind:

A placeholder callBackUrl is fine. Some generators require the field even when you intend to poll — pass any well-formed URL; you do not need to receive the callback.
Know whether the status endpoint is paid or free. If it answers 402, each poll is a paid call (see the next bullet). If it is free (non-402) on a cataloged service, the Router relays only the status and withholds the body by default — the free-follow-up window is off unless the deployment enabled it and the merchant declared the path — so a free poll can return 200 with no result. Check the endpoint on the listing.
Give every poll a fresh X-Router-Request-Id. The Router de-duplicates on that id, so reusing one makes each repeat a duplicate that is refused (409 BCK.ROUTER.0002, the original paymentId in params, no result) — it is not a new charge, but it never reaches the service either, so a naive poller stalls and never advances. A fresh id per poll advances it — and on a paid (402) status endpoint each real poll is a separately-billed call (the merchant charges per status check), so bound the number of polls against your delegation cap. (A free status endpoint relays with paid: false — no charge.) The Catalog MCP’s pay_service exposes a fresh flag that mints the fresh id for you.
Read the generate and status endpoints — and the field that carries the taskId and the result — from the service’s Catalog detail (requestExample / responseFields).

The principles that make it smooth

These are the habits that turn trial-and-error into a clean run. Treat them as the manifesto:

Discovery is free — use it first. Confirm a service’s slug, price, and endpoints from the live feed before every task. Prices and listings drift.
A failed call is not reliably free — don’t treat it as a cheap probe. Once the payment credential is minted, the merchant leg stands even if the upstream call then errors; only the routing fee may be released, and only on specific paths. Whether the merchant leg settles before or after the upstream 2xx depends on the call mode. Confirm how a service wants to be called from its listing and docs, not by paying to find out — see when a fee is not collected.
Address a service by its slug and let the Router resolve the endpoint. Don’t fight it with hand-assembled sub-paths — the common failure is a mis-resolved path, not a payment problem.
Put target URLs in the request body, never in the path. A security guard blocks anything in the path that looks like it changes the destination host.
Give every purchase a stable idempotency id. Reuse the same id when you retry, so a network hiccup never double-charges; use a fresh id only for a genuinely new purchase.
Async services: poll, don’t wait on a callback. Synchronous services are simplest, but async ones (e.g. media generation) are fully supported — see Async services above. The one trap is a naive poller: give each poll a fresh idempotency id. Reuse one and the Router refuses each repeat as a duplicate (409, no charge) so the poll never advances; a fresh id per poll advances it, and each paid (402) poll is a separately-billed call.
The delegation is the source of truth for spend. Reconcile against your delegation’s remaining budget, not a local tally.
Prove the flow cheaply — payment is Live-only. Sandbox can rehearse the mechanics against its two free testnet test merchants, but no real service is payable there (its Router funds testnets only) — so validate discovery → pay → result end-to-end on Live with a small delegation cap and the cheapest sub-cent service before scaling spend up.

Step 4 — Track and reconcile spend

Read your delegation’s remaining budget and the Nevermined payment ledger to see exactly what each call cost and how much of the cap is left. This is also your audit trail. See the environment’s OpenAPI reference for the delegation and payment endpoints. When a call errors on /router/proxy or /router/svc (BCK.ROUTER.0019 / 0020) — on /router/route the same condition arrives as the envelope’s status with body: null, no typed code — status is the primary read — it is what you got (a non-2xx leaves the row unsettled). On the x402 rail there is also merchantSettlementObservedAt: when it is set alongside status: Issued/Failed, the merchant redeemed the payment on-chain and delivered nothing (charged-but-undelivered — worth alerting on). It is null on a clean settlement and on both MPP rails (which cannot record it), so null is not proof you weren’t charged — fall back to txHash / status there. Either way, the Router never takes its own routing fee for a call that did not deliver.

Safety & etiquette

Live means real money. The Catalog is Live-only — keep delegation caps tight and rehearse with a sub-cent service before scaling.
Mind the data. Some services return personal or third-party data; use them only where you have a lawful basis, and remember the query is sent to a third-party vendor.
Protect the key. Never commit it, log it, or paste it into a shared transcript.

Links, in one place

Catalog (browse): nevermined.app/catalog
Catalog feed (all services): ai-catalog.json
Using the Catalog from your web assistant (the no-code counterpart to this page): /products/catalog/from-your-web-assistant
Catalog MCP: /products/catalog/mcp
Router quickstart: /products/catalog/router/quickstart
An agent buying on its own (worked end-to-end run): /products/catalog/router/agent-autonomy
Nevermined app (sign in, keys, delegations): nevermined.app
Get an API key / authentication: /integrate/authentication/overview · the agent-facing manifest: nevermined.app/auth.md
x402 explained: glossary · reference: /api-reference/typescript/x402
Stablecoin payments: /integrate/patterns/stablecoin-payments
Docs index: /getting-started/overview · SDK/API index: llms.txt
API reference (OpenAPI JSON): docs-json
GitHub: nevermined-io · Contact: nevermined.ai/contact-us

Learn

Nevermined Catalog

Payments

Solutions

Organizations

Integrations

Payment Patterns

Components

Specs

See it in action

What the Catalog is

The mental model

Step 0 — One-time setup (a human is needed once)

Step 1 — Set a budget you cannot exceed (the delegation)

Step 2 — Discover services (free, no key required)

Step 3 — Connect the harness to the Catalog

Using the Catalog MCP

The calling convention (one canonical shape)

Async services (generate, then poll)

The principles that make it smooth

Step 4 — Track and reconcile spend

Safety & etiquette

Links, in one place

​See it in action

​What the Catalog is

​The mental model

​Step 0 — One-time setup (a human is needed once)

​Step 1 — Set a budget you cannot exceed (the delegation)

​Step 2 — Discover services (free, no key required)

​Step 3 — Connect the harness to the Catalog

​Using the Catalog MCP

​The calling convention (one canonical shape)

​Async services (generate, then poll)

​The principles that make it smooth

​Step 4 — Track and reconcile spend

​Safety & etiquette

​Links, in one place

See it in action

What the Catalog is

The mental model

Step 0 — One-time setup (a human is needed once)

Step 1 — Set a budget you cannot exceed (the delegation)

Step 2 — Discover services (free, no key required)

Step 3 — Connect the harness to the Catalog

Using the Catalog MCP

The calling convention (one canonical shape)

Async services (generate, then poll)

The principles that make it smooth

Step 4 — Track and reconcile spend

Safety & etiquette

Links, in one place