MCP server

BuiltFixture onlyChecked 16 November 2026

In short

  • An MCP server your agent can ask about costs, balance, tools and memory.
  • Add it to Claude Code with one command.
  • Cost tools need no key; the rest need PETROVA_API_KEY.

Petrova is not live. The MCP server talks to a Petrova API in test mode. No real money moves, and only local fixture tools can be paid.

The MCP server gives an agent six tools: sign itself up, find a paid API, read how to call it, call it within a maximum charge, read a call again, and say whether it helped. It runs two ways: over stdio on your machine (pet mcp), or hosted over Streamable HTTP at <your origin>/mcp.

One-line setup

Say this to the agent:

Set up Petrova from <your origin>/skill.md

skill.md gives the agent the hosted MCP address and the command-line way, and the steps after.

Hosted MCP

<your origin>/mcp (apps/api/src/mcp-http.ts), Streamable HTTP, the same six tools.

  • With a key: send Authorization: Bearer <agent key>. The session acts as that agent.
  • With no key: the session can call start. It signs a new agent up and shows the key once, with how to send it next time (over HTTP there is no file to keep it in). The other tools need a key.
  • A session is bound to the key it started with; a later request with another key is refused. Idle sessions end after 30 minutes.
  • It runs with the production start (npm run prod:local here, or a server), not with npm run dev. Sign-in with OAuth is not built: the key is the only credential.

Test: tests/integration/mcp-http.test.ts.

Add it to Claude Code

Save the key once with the command line, then point the client at pet mcp. The key is read from the saved profile, so it never goes in the client's settings:

printf %s "$PETROVA_KEY" | npm --prefix "$PWD" run --silent petrova -- login --key-stdin
claude mcp add petrova -- npm --prefix "$PWD" run --silent petrova -- mcp

Without the CLI, npm run mcp reads PETROVA_API_KEY and PETROVA_API_URL from the environment.

An agent with no key at all can start with the start tool. Under pet mcp the key it gets is saved to the profile file (owner-only); under npm run mcp it lives in the server for the session. Either way the model never sees the key.

The six tools

If your agent already knows a provider's API, it calls it directly. Otherwise it searches, and inspects when the inputs are unclear.

ToolWhat it doesSpends
startNo key: sign up with a name (a key at once, $0, nobody owning it yet), then the status with the one link for your person. With a key: what you can spend nownever
searchFind an operation for what you need. Each result names provider, method and path, its trust tier and its pricing. Verified tools rank first; tools the last check found gone are left outnever
inspectOne operation's call-ready request: each field with its type, whether it is required, and where it goes (path_params, query, headers, body)never
callCall it: provider, path (or tool_id), the inputs where the API takes them (or one inputs object), a new idempotency_key and, above $1.00, max_costonly a checked 2xx answer, once
get_callRead a call by invocation_id or the original idempotency_key. For a lost answer or a pending callnever
report_outcomeSay whether it helped: succeeded, failed or not-useful. One report per callnever

Example arguments for call:

{ "provider": "exa", "path": "/search", "body": { "query": "machine payments" }, "max_cost": "0.05", "idempotency_key": "task-17-search-1" }

Every answer has one shape

call, get_call and start answer in the shape described in the agent's journey: kind, refused_by, reason, message, next_action (with the exact CLI command, the next MCP tool and its arguments, and the link and say_to_person when a person is needed), receipt, balance and warnings.

kindWhat to do
okUse response.body. The receipt says what it cost. Then report_outcome
needs_fundingPass next_action.say_to_person to your person word for word (a first link's sentence carries the 6-digit code the page asks for, also in next_action.link.code); call start until it says ok
over_limitTell your person. You cannot raise a limit
needs_approvalPass next_action.say_to_person on the same way (link and code). Your person must say yes. get_call later with the same key
price_changedWith next_action.accept_terms: repeat the same call, same key, adding accept_terms, only if terms fits. Otherwise a new key and a higher max_cost, or another tool
failedCharged $0. Try another tool from search
pendingget_call with the same key. Never call again with a new key to check
pausedWait
refusedrefused_by says who; follow next_action
not_startedNothing began with that key: sending the call again with it is safe

Refusals are answers, not protocol errors. Only an argument that fails the tool's schema is an error, and it names the field.

Money. The maximum is $1.00, fee included, unless you set max_cost. Only a 2xx answer that passes its checks (not empty, not error-shaped) is billed, and only once: the same key always finds the same call. A price above your maximum never charges you: it comes back as terms. Your card's per-call limit, allowance, shared budgets and approval line still apply, and a person's approval still applies above that line.

Trust tiers on every result: listed (a directory lists it), verified (an unpaid request got a valid payment challenge matching the listing) and proven (a real payment with a real signer got a checked result). Test-mode payments can never make a tool proven.

Who paid. receipt.paid_by is wallet or customer_account. With credential_mode: "customer" and a connection_id, the call uses your own provider account (connected by an owner) and never falls back to wallet funds.

Other areas, when asked for

The default list is the six tools. Ask for more with pet mcp --toolsets account,models, or PETROVA_MCP_TOOLSETS=account,models for npm run mcp (all for everything):

ToolsetTools
accountsetup_check, balance, cards, reconcile
legacyThe earlier tool-id path: tools_search, tools_discover, tools_inspect, tools_quote, tools_call, calls_get, calls_list, calls_cancel, runs_get, tools_rate
modelsmodels_catalog, models_estimate_cost, models_compare, models_cache_advice, models_best_route (no key needed)
memoryremember, recall, forget, memory_list, memory_export, repo_context
sellerseller_validate, seller_submit, seller_status, score_lookup
chainchain_watch_create, chain_watch_poll, chain_watch_stop

There is no settle or hold tool, and no tool that takes an API key: a key in a tool argument would sit in the agent's transcript.

Changes from the earlier server

  • The default is six tools in the order an agent uses them; start was added when the agent journey merged. The earlier tool-id path is the legacy toolset, unchanged.
  • call and get_call answer in the journey's kinds (ok, needs_funding, ...), replacing responded, pending, requires_action and refused.
  • call addresses a tool by provider and path. tool_id still works.
  • A price above the maximum is offered as terms instead of refused.

Last checked against the code: 16 November 2026. Something wrong? The source of this page is in the repository, so a fix is one edit.