MCP server
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:localhere, or a server), not withnpm 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.
| Tool | What it does | Spends |
|---|---|---|
start | No 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 now | never |
search | Find 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 out | never |
inspect | One operation's call-ready request: each field with its type, whether it is required, and where it goes (path_params, query, headers, body) | never |
call | Call 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_cost | only a checked 2xx answer, once |
get_call | Read a call by invocation_id or the original idempotency_key. For a lost answer or a pending call | never |
report_outcome | Say whether it helped: succeeded, failed or not-useful. One report per call | never |
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.
| kind | What to do |
|---|---|
ok | Use response.body. The receipt says what it cost. Then report_outcome |
needs_funding | Pass 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_limit | Tell your person. You cannot raise a limit |
needs_approval | Pass 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_changed | With 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 |
failed | Charged $0. Try another tool from search |
pending | get_call with the same key. Never call again with a new key to check |
paused | Wait |
refused | refused_by says who; follow next_action |
not_started | Nothing 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):
| Toolset | Tools |
|---|---|
account | setup_check, balance, cards, reconcile |
legacy | The earlier tool-id path: tools_search, tools_discover, tools_inspect, tools_quote, tools_call, calls_get, calls_list, calls_cancel, runs_get, tools_rate |
models | models_catalog, models_estimate_cost, models_compare, models_cache_advice, models_best_route (no key needed) |
memory | remember, recall, forget, memory_list, memory_export, repo_context |
seller | seller_validate, seller_submit, seller_status, score_lookup |
chain | chain_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;
startwas added when the agent journey merged. The earlier tool-id path is thelegacytoolset, unchanged. callandget_callanswer in the journey's kinds (ok,needs_funding, ...), replacingresponded,pending,requires_actionandrefused.calladdresses a tool by provider and path.tool_idstill 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.