MCP tool reference

SuperCapture 1.0.445 exposes 24 tools over the Model Context Protocol: 7 at the Read-only level, 3 more at Interact, and 14 that need Full. A client that holds the bearer token gets Full by default and can downgrade itself with the X-Access-Level header. This list was exported on 2026-10-02.

Capture and recording

Tool	Access	What it does
capture	Full	Capture into the library: a window, a rect, a display or every display, SuperCapture itself, or through the browser extension a tab's page, a presentation or a bookmark. A new item lands in folder (a rel path from library_find folders, '' the save root), else where the user is looking (state's capture_destination), named by the naming template; name fills its name slot (else AI rename names it, when the user has it on). open shows it in its editor, waiting for the load. The result names it (id, path). To look without saving, screen look; a page by its address, capture_url.
capture_url	Full	Capture a web page by its address: the SuperCapture browser extension opens the URL in a new tab of the user's browser, captures it - the visible viewport, or with full_page the whole page scrolled and stitched - then closes the tab. For a page the user doesn't already have open; for one they do, capture page_visible / page_full with tab_url. Nothing on the page is clicked or typed into. http and https only. The page loads as the user's browser would load it, signed in where they are, so the user is asked to approve every call. Saves into the folder currently open in the gallery, or the save root if none; pass 'folder' to target a specific folder. With a bookmark's id instead of a url, its page is fetched again into it (Recapture), asked about the same way.
record	Full	Record the screen or audio as the recorder does, its panel on screen. One recording runs at a time; state lists it (an agent's, or one the user started: pause, resume and stop act on theirs as the panel's buttons do). A recording lands in folder (a rel path, '' the save root), else where the user is looking when it starts. stop's result names the new item (id, path). With into, the take goes into the video open in the video editor instead, as a clip by the playhead (clip_id), not into the library.
screen	Interact	What is on screen, without saving anything: the windows and displays, a picture of a window, rect, display or SuperCapture dialog, and where a SuperCapture control is. Every position is in global screen points (points on macOS), the space input and capture take. To place a control on a window's picture, subtract the window's x and y and multiply by the picture's pixels per point.

Documents

Tool	Access	What it does
describe	Read-only	How the document tools work: the conventions every tool follows (colour, points, rects, percent, time), the document types and their element kinds, each kind's properties (type, unit, range, values) and the actions doc_edit's do takes. With no arguments, an overview; with doc_type, that type in full; with kind, one kind.
doc_edit	Full	Change a document: a batch of operations applied as one undo step, all or nothing. Each op is one of {op: add, kind, props, ref?, parent?} (ref names it '$x' for later ops), {op: set, target, props} (target: an element id, a $ref or a section name), {op: delete, target}, {op: order, target, to: front|back|forward|backward|index}, or {op: do, action, target?, ref?, ...args} (ref names what an action makes, e.g. a duplicate's copy). Open in its editor, the edit shows at once and is undoable there; closed, it is saved as Save & Exit saves. The result lists created ids (an action's too) and every touched element as doc_read returns it. describe lists the kinds, properties and actions.
doc_read	Read-only	A document's model: every element (annotations, images, tails...) with all its properties, and its sections (canvas, stage, camera, document), each in the shape doc_edit's set takes. Points and rects are the picture's own pixels (canvas.picture_at says where the picture sits in doc_render's image). With no id, the item open in an editor, else the gallery's current item. describe explains every kind and property.
doc_render	Read-only	A picture of a document as it exports: an image with its background and frame, a video's frame at ms (edited time, cuts removed), an audio recording's edited track as a waveform (seams between regions marked, the trimmed-off parts dimmed), a scancode, a font's specimen sheet. With no id, the item open in an editor, else the gallery's current item; the result says which (id, doc_type) and whether it drew the open editor or the saved file. For an image, scale (render pixels per picture pixel) and picture_at (where the picture's top-left is in the render) relate the two; or pass coords: "render" to doc_read / doc_edit to work in the render's pixels.
editor	Full	The editors as a user drives them: open and close, undo and redo, the selection, the armed tool, the properties panel, the view's zoom and page, and the library picker. What a document holds is doc_read / doc_edit's.
export	Full	Write an item to a file the way its editor's Export… does. An image: its edited picture (annotations, crop, background and frame, the free tier's mark when the user edited it) as png, jpeg or webp, sized, padded and watermarked, or every page as a pdf, or a SuperCapture archive (scap). An image file in SuperCapture's temp folder (path) is written as the file is, beside itself unless output_path says. A video's edited project (cuts, speeds, crops, annotations, zooms, camera, stage, captions, the audio mix) encoded as a video (on the free tier an mp4 or mov ends with a ~2 s SuperCapture card, counted in duration_ms), an animated picture, its audio alone (m4a), a SuperCapture archive (scap), or one frame as a png at at_ms; an audio recording's edited track as m4a, mp3, wav or scap; a scancode as png, svg, pdf, jpeg, webp or eps; a font as its own file (font). Those three take format and output_path only. An animated picture plays as many times as the video's loop says (doc_edit set document loop). bookmarks, with no item, writes every bookmark and browser capture's address as a browser-importable bookmarks file. clipboard puts an item's edited render on the clipboard (a picture as a picture, anything else as its file); print shows the system print panel for an image, PDF or bookmark, where the user prints or cancels. Both take the item only. Into output_path, which must be in a folder the user approved (made if missing) and is required for an item; bookmarks without one refreshes the library's bookmarks.html. Reports progress; a long video takes minutes. The result names the file (output_path).

Library

Tool	Access	What it does
library_add	Full	Bring new items into the library: files and downloads, compositions of images, a new scancode, a font's specimen, a linked folder. A new item lands in folder (a rel path from library_find folders, '' the save root), else where the user is looking (state's capture_destination), named by the naming template; name fills its name slot. The result lists the new items (items: id, path); the Activity view's Undo moves them to the Trash.
library_delete	Full	What can't be undone, so the user approves every call: deleting items in the Trash for good, emptying it, unlinking a linked folder, rebuilding the index. To remove items undoably, library_edit trash.
library_edit	Full	Change items and folders in the library as the gallery's menus do. Items are ids (from any result; a path or name works too); every one must resolve before anything changes. Each change is undoable from the Activity view. What a document holds is doc_edit's; deleting for good is library_delete's.
library_find	Read-only	Find items and folders in the library. Items carry id: hold on to it, not the path, which changes when AI rename lands. type is one vocabulary for every action: image, video, audio, document, pdf, font, bookmark, slideshow, scancode, video_loop, screen_recording, recordings.

Sharing

Tool	Access	What it does
share	Full	Share items and folders as the Share hub and Share dialogs do. What is sent is the edited render (an annotated image flattened, a video with its edits). A web page, a folder's page and an invitation are asked about every time, and so is taking a page down or deleting a comment; a send or a comment isn't, but in the chat one about something the user didn't point at, or in words that aren't theirs, is. Items in hidden folders can't be shared.

App and input

Tool	Access	What it does
input	Interact	The real mouse and keyboard, as system input events: the OS cursor moves, and the capture overlay and a recording's cursor track see it. SuperCapture is brought to the front first; a click can land in any app under the pointer, keys go to SuperCapture. The user approves it once per session. Needs the macOS permission to control the computer (Privacy & Security → Device control & data access; Accessibility before macOS 27): without it, a call asks macOS to prompt and fails, and a grant applies from the app's next launch. Positions are global screen points (screen list, screen locate). Call view wait_idle before looking at the result.
settings_get	Read-only	The settings an agent may read, with their current values, types and descriptions. Settings not listed here aren't reachable by design (credentials, the agent's own permissions, where the library lives).
settings_set	Full	Change settings, as the Settings window does: saved, and in effect at once. Only the settings settings_get lists; every value is checked before any is set. The result has each one's value before and after.
state	Read-only	What is on screen and selected: the shell and mode, the open editor and its item (editor_item_id), armed tool, loading, panels, Quick Look, the library picker, where the next capture lands, the gallery's current and selected items, browser-extension connections, any recording in progress (an agent's or the user's), and temp_dir, SuperCapture's temp folder, where files are staged for library_add import. Check it first.
view	Interact	The app as the user sees it: what the gallery shows and what is selected, Gallery or Reader mode, Quick Look, the main window's panels, shell, size and theme, the Settings and Workflows windows, and Show in Finder. Changes no item and no setting (theme here is for this session only). state reports most of it.

Browser extension

Tool	Access	What it does
browser	Full	The SuperCapture browser extension's connections, a tab's geometry, and the headless browser for capture runs with no one at the screen. Nothing on a page is clicked or typed into: an agent that needs to drive a browser uses its own browser tools.

Files and workflows

Tool	Access	What it does
files	Full	The file steps workflows chain, inside the library's reach: a source is a library item or a file in SuperCapture's temp folder ({temp_dir} in a workflow), and a destination an approved folder (Settings → AI MCP Info) or the temp folder. Replacing a file outside the temp folder asks the user first.
workflows	Full	The user's saved workflows: the steps they set up to run after a capture (copy it to a folder, rename it, export or share it). An agent lists them and runs one on an item; making or changing them is the user's, in the Workflows window.

Diagnostics

Tool	Access	What it does
diagnostics	Read-only	The app's own health, for debugging it.