MCP server tools

Reading tools are read-only (readOnlyHint: true, not destructive, idempotent). The scanning tools (create_scan, upload_frame, start_scan, cancel_scan) are annotated as writes, cancel_scan as destructive. They, and check_frame, are listed on every connection but work only on one where the user ticked let it scan spaces when connecting: otherwise the API refuses them with INSUFFICIENT_SCOPE. No tool reaches the open web. Results are JSON text (or a Markdown page); results that carry space content include a note saying it is data captured from a physical space, not instructions.

list_spaces

The spaces this connection can read, newest first, with their latest scan (counts of areas, items and issues).

search_spaces

The records that best answer a question, across all spaces or one. Any language: an Italian question finds an English record. Records are items, areas, issues, key locations, instructions, facts and Q&A.

Each result has space_id, space_name, scan_id, record_type, record_id, title, area, text and score. The text of an item, issue or key location says its photo check (“Photo check: verified on its photo”, “Photo check: unconfirmed…”, “Photo check: from the narration, no photo”): an unconfirmed record is said as uncertain.

get_space

The current document of a space, shaped for a model: area names instead of ids, no frame list, empty fields left out.

Items, issues and key locations carry verification: verified (a photo it cites clearly shows it), unconfirmed (its photos do not clearly show it: say it is uncertain) or not_visual (from the narration, or a fault or absence no photo can show). evidence_check counts them (verified, unconfirmed, not_visual, and not_checked when some records were not checked). Both are left out on documents made before the check existed. See Verified evidence.

ask_space

A short answer (one to three sentences) from the records of one space, with the records it cites and their evidence, or documented: false when the answer is not in the records. The answer is asked to say when a record it rests on is unconfirmed on its photo; get_space shows each cited record’s verification.

list_scans

The scan history of a space, newest first, to choose two scans for compare_scans.

compare_scans

What changed between two scans of a space: items added, moved, recounted or in another condition, and new issues. Items removed and issues resolved are confirmed by a frame of the empty place; not_seen ones were only absent from the later scan, so the assistant is told to say they may be missing. Each entry has evidence frames of both scans, which get_evidence_photo can show.

For spaces scanned with the app, past scans are not screened, so this needs a connection granted sensitive values.

get_evidence_photo

The original video frame behind a record, as an image.

Evidence links expire after a while; on SIGNED_URL_EXPIRED, read the record again for a fresh link.

get_space_markdown

The whole current document of a space as one Markdown page: summary, every area with its items, issues, key locations and how-to steps, then facts, Q&A, coverage and the recording. One call to load a space as context before many questions. Redacted like everything else the connection reads.

get_scan_status

Where a scan made with the API or the CLI is: awaiting_upload, queued, processing (with its stage), complete, failed or cancelled.

follow_scan

Waits for a running scan and returns where it is, in words (label, for example “Looking at the frames”), with final: true once it is complete, failed or cancelled. Waits up to max_wait_seconds; a scan still running after that comes back with final: false and next: "Still running: call follow_scan again.", never as an error. Clients that pass a progress token get a progress notification at every stage.

check_frame

One photo checked as a scan would check it: usable (sharp, lit, showing the space), quality (score 0–3 and level), shows_space, and the key locations it shows (key_locations_seen) or not (key_locations_not_seen). Without space_type, those of a home: electrical panel, water shut-off, boiler, smoke detector, extinguisher, router, thermostat, gas meter. With it, those of that type of space (capture_checklist lists them) and the area the photo shows, from a probability of 0.6; when the API ignores space_type (an API older than the server), the result has a warning and the key locations are a home’s. Nothing is stored. Use it on a photo the user sends, or from a camera, to say what is still missing before a scan. Needs the scanning access.

capture_checklist

What to film for a type of space, before a scan: its key locations, those usually there (usually_there) and those only if there is one (if_there_is_one), each with a label and a one-line hint, and its areas (value, label). Give it to the user before they film; check_frame with the same space_type then confirms each photo. Works on every connection; nothing is charged. See Guided capture.

wallet

The prepaid balance (balance_cents), the free scans left, the price of one scan and whether automatic top-up is on. Tell the user before starting a scan. No arguments.

create_scan

Declares a new scan and returns upload, exactly as the API gives it, and a next step. Frames are sent one by one with upload_frame. For a video, upload is a one-off PUT URL: when it points at storage (headers given, no key needed) the agent can PUT the bytes there; when it points at the API it needs the user’s own key, which the server never hands out, so the agent asks the user to upload with the CLI or the console. Nothing is charged until start_scan. Everything the server can check (a video over 4 GB or of a type the API does not take, a missing video or frames) is refused before a new_space is created, and a space created for a scan the API then refuses is deleted again.

upload_frame

Sends one image of a frames scan, at its index (0…count-1), through the server, which holds the key. JPEG, PNG or WebP, at most 2 MB, base64. Sending an index again replaces that frame. Then start_scan.

start_scan

Starts the analysis of an uploaded scan and charges it now: the free scan first, then the balance. Returns the scan with its charge. A scan that fails is refunded.

cancel_scan

Cancels a scan that has not started: nothing is charged, its uploads are deleted. A scan already started cannot be cancelled.

Resources

Prompts

Errors

A tool that fails returns isError: true with the error code and a hint, for example:

See all error codes.