Adaver MCP tool reference

This page describes the three tools an agent sees at https://api.adaver.nuvai.dev/mcp. The text comes from the server code (crates/adaver-server/src/mcp/). If the code and this page ever differ, the code wins: the agent reads the tool descriptions from the server itself.

Overview

A tool the key has no permission for is not shown to the agent. If the agent calls it anyway, the answer is "unknown tool", the same as for a tool that does not exist.

The server keeps no session. Every request stands alone. Each answer is one JSON message (no event stream).

list_presets

"Lists the five vectorization presets and what each is for. Free, changes nothing."

Input: nothing.

Output (structuredContent, and the same JSON as text):

{
  "presets": [
    { "name": "auto", "use_for": "...", "default": false },
    { "name": "high_quality", "use_for": "...", "default": true }
  ]
}

get_balance

"Shows how many images the account has left and whether the free image is still unused. Free, changes nothing you can see."

Input: nothing. Needs: scope balance.

Output:

get_balance shows the account. It does not show how much of a key's daily limit is used. A key that is at its limit learns it from the daily_cap_reached error (with used, limit and resets_at).

vectorize_image

"Turns a PNG, JPEG or WebP image into a clean SVG. THIS CHARGES 1 IMAGE to the account (the account's one free image counts); if the call fails, the image is given back."

Needs: scope vectorize.

Input

Send exactly one of image_url and image_base64. Unknown fields are refused.

How the image is downloaded from image_url: https only, at most 3 redirects (each one checked again), and private or internal addresses are refused. The type is read from the bytes, never from the file name.

Output

On success (structuredContent, and the same JSON as one text block):

Inline SVG or link

About the link:

• No key is needed to open it. Anyone who has the address can read the SVG until it ends. Do not share it.
• It answers image/svg+xml with no-store, nosniff and a sandbox content security policy, so a browser never runs code from it.
• After it ends, or for a wrong address, the answer is 404.
• One account keeps at most 10 live links. A new one removes the oldest.

These are the server's default limits. The operator can change them (inline 1 KB to 1 MB, link 60 s to 1 hour).

Charging

• One call that finishes spends 1 image. The account's one free image counts.
• If the call fails after the image was held, the image is given back. If the client goes away or the call takes too long, the image is given back too.
• Nothing is charged for a refusal: bad input, limits, daily_cap_reached, content_refused, confirmation_required, insufficient_images and the other errors below.

Content check

Every image is checked automatically for content we do not trace (Azure AI Content Safety), the same check as on the website. A refused image is the tool error content_refused and charges nothing. A key that sends several refused images in an hour is paused for the rest of the hour (too_many_refusals, see Limits). If the check cannot be made at that moment, the image is traced anyway.

• Every new call for the same picture is a new trace and spends 1 more image. Call again only when the user wants a new trace.

Safe retries

The idempotency_key makes a retry safe after a network error or a timeout.

Always make a fresh random UUID. Never copy an example UUID.

Confirm mode

A key can be set to confirm mode. Then no call charges until the user agrees.

1st call (no confirm_token)   ->  error "confirmation_required" with confirm_token, price, expires_in_secs
                                  nothing is charged
agent asks the user: "Spend 1 image?"
user says yes                 ->  same call again + confirm_token  ->  charged once
user says no                  ->  do not call again

• The token works only for the same key, the same picture and the same settings.
• It lives 10 minutes by default (expires_in_secs says how long).
• If the first call had an idempotency_key, the token is that same value. Sending both is fine. A different idempotency_key next to the token is refused.
• Sending the token again after the charge is a free replay, never a second charge.
• A client that supports MCP questions (elicitation, protocol version 2026-07-28 or newer) gets a yes/no box instead. "No" answers confirmation_declined.

The account page has no switch for confirm mode yet, so keys made there have it off.

What confirm mode can and cannot do. The question goes through your AI client, and Adaver cannot see who answered it: the agent itself receives the confirm_token, so an agent that ignores the rule (a bug, or instructions hidden in a page it read) can send the token without asking you. Confirm mode is a seat belt for well-behaved clients, not a lock. The hard limit is the key's daily cap: the server enforces it whatever the agent does. Set the cap to what you are willing to spend in a day.

Limits

A free replay still works when the key is at its daily limit.

Errors

There are two kinds of errors.

1. Tool errors. The HTTP answer is 200 and the tool result has isError: true. It has one text block that holds a JSON object:

{
  "code": "daily_cap_reached",
  "message": "This key has used its daily limit of 20 images. ...",
  "retry_after_secs": 3600,
  "request_id": "..."
}

It always has code, message and request_id. Some have more: field (which input is wrong), limit, actual, retry_after_secs, free_needs_verification, confirm_token.

2. HTTP errors. The request is refused before any tool runs. The body is JSON with code, message and request_id. The x-request-id header has the same id.

HTTP errors

Tool errors of vectorize_image

get_balance can answer internal. list_presets has no tool errors.

Server metadata

GET https://api.adaver.nuvai.dev/.well-known/oauth-protected-resource (and .../oauth-protected-resource/mcp) returns a small public JSON document that names the resource (.../mcp) and links to the documentation. The 401 answer points at it. Agent keys do not need it today; OAuth sign-in will.