API reference

MCP

Let another AI agent build with Graspable. Set-up for Claude Code, Codex and other MCP clients, and the list of tools.

Graspable has an MCP server. With it, another AI agent can create projects, ask Graspable's agent to build, follow the run, read and write files, check the result and start the preview.

Set it up

Install grasp through Settings → Plugins and connectors → Use Graspable from other tools in the desktop app. Agent-operated installation is covered in CLI. Direct file editing and local checks work without signing in to another AI account. Configure Graspable's AI account only if you want to use start_run to delegate generation.

Claude Code

claude mcp add graspable -- grasp mcp

Codex

codex mcp add graspable -- grasp mcp

Any other MCP client that starts a program:

{ "mcpServers": { "graspable": { "command": "grasp", "args": ["mcp"] } } }

Over HTTP. The same server is at POST /mcp of the local API, with an access token:

{ "mcpServers": { "graspable": { "type": "http", "url": "http://127.0.0.1:<port>/mcp", "headers": { "Authorization": "Bearer <token>" } } } }

Browser checks

For web projects, Graspable checks with Chrome for Testing, downloaded from Google into its own runtime folder. On Windows and Linux it uses Chrome, Edge, Chromium or Brave already on your computer and downloads Chrome for Testing only when none is there; on a Mac it downloads it in any case and uses your own Chrome until the download is done, because an installed Chrome tries to update its own app when a check starts it. The first check waits for that download. It does not use your browser profile.

If the download or browser launch fails, the report can contain a skipped check even when the build passes. Read the browser result before treating the scene as tested. In the desktop app, Settings → Components shows the browser and its download status. See check screenshots for returning the available picture to your agent.

Next desktop release: browser checks on macOS use a separate test keychain, avoiding login-keychain prompts during headless startup. This fix is not included in 0.19.0.

Tools

Tool What it does
inspect_motion Validate a motion JSON file and inspect its pose at a frame; read-only, experimental. See motion inspection
list_templates The project templates
list_projects The person's projects
create_project Create a free web project. Create premium or native projects in the app first
list_files, read_file, write_file Work with a project's files
start_run Ask Graspable's agent to build or change something, in plain words
get_run What a run has done so far. Waits for it to finish or to need an answer
approve Answer a run's approval request
cancel_run Stop a run
list_runs Earlier runs of a project
check_project Build and check a project with its browser or native engine
project_history The project's versions, newest first: one per run that changed files
restore_project Put the project's files back to a version. Recorded as a new version
start_preview Start a web project’s live preview and return its local address

Version 0.17.2 also includes read_usd and write_usd for scoped USD inspection, separate edit layers and supported scene conversion. read_motion, edit_motion, export_motion and read_otio_edit cover animation takes and editorial handoffs. inspect_film lists delivery summaries or reads exact video revisions; encode_spatial_video creates a native Apple master and returns a small receipt without movie bytes. See film delivery. Use Graspable 0.17.2 or later for these tools. See OpenUSD scenes and the animation API.

Edit with your connected agent

  1. Use list_projects to find the project, or create the free react-xr-developer starter with create_project.
  2. Wait for list_projects to report install: done. An installation failure needs attention before editing or building.
  3. Use list_files and read_file to inspect the source. write_file takes the complete replacement file, with a project-relative path. Preserve unrelated edits and coordinate with anyone else editing that file.
  4. Call check_project. It builds a web project and loads it in a headless browser. Correct any errors and check again.
  5. Call start_preview, then inspect the running scene. Return the preview address and explain any device checks still needed.

The connected agent supplies the edits through its existing AI account. This flow does not call Graspable's model or spend Graspable Credits. Template entitlements and any separately requested paid services still apply. Testing the intended interaction is a separate step from a successful build and browser load.

Try a small scene edit

With the free React XR starter open, ask your connected agent:

Change the New ball button to New pair. Each press should add two balls, keep the existing limit of eight, and show the current ball count on the sign. Tidy up should still leave one ball. Edit the files yourself, then use Graspable to check and preview the result.

After the check passes, try the interaction: the count starts at one, becomes three after one press, stops at eight after repeated presses, and returns to one with Tidy up. This exercises source editing, scene state and a control that already belongs to the template. It needs no new assets or generation service.

The edited starter scene with three balls after pressing New pair

This example was checked with Graspable 0.18.1 on macOS, including those mouse interactions in a desktop browser. It is not a headset or phone AR test.

Work on an existing native project

Create a Unity, Unreal Engine or Apple Vision Pro project in the desktop app with a plan that includes native XR. This supplies the plan authorization that create_project does not currently obtain through MCP. Keep the corresponding engine tools installed on the same computer.

Your connected agent can then select the project with list_projects, read and edit its source, and call check_project. The check uses the native engine: Unity play mode, the visionOS Simulator or Unreal's desktop game view. Read the summary; a skipped run is not a successful runtime test. Open the project's preview in Graspable to inspect the picture. start_preview is for web projects and cannot return a browser address for a native app.

These checks do not verify hand input, room tracking, comfort or performance on a physical headset. See Native XR for engine setup and device testing.

Check screenshots (0.19.0 and later)

Graspable 0.19.0 and later supports an optional includeImage: true argument to check_project. It returns the available screenshot as an MCP image alongside the text report, so your connected agent can inspect the result. Graspable 0.18.1 does not return that image yet.

The screenshot is sent to the connected agent only when requested. A runtime failure can still include a useful picture. Missing or oversized images produce a note; a text-only result is not visual verification. An unchanged project may reuse its previous check and picture, which the summary identifies. Test the intended interaction separately: the image does not prove that a button or gesture works.

The same release adds engine kind and required plan feature to list_templates, engine kind to list_projects, and guidance for direct editing when an agent connects. No additional model sign-in is needed for direct edits or checks.

Delegate to Graspable's agent

Configure its AI account first in Settings → AI for the agent or through grasp login. Delegated runs use that account's allowance or balance.

  1. create_project, or list_projects to find one.
  2. start_run with the request. It returns a run id at once.
  3. get_run with that id until the state is completed, failed or cancelled. Pass the since number from the last answer to get only what is new.
  4. When get_run lists needs_approval, ask the person. Call approve only when they have authorized that action; otherwise leave the request for them to answer in Graspable.
  5. For a web project, use start_preview to look at the result. For a native project, open its preview in Graspable.

A web run uses build and browser checks; a native run uses its engine checks. Read the reported outcome, including any skipped checks. A failed check goes back to Graspable's agent, up to three times, before the run fails.

What the other agent may do

Each tool call is counted by the tool's name and the client's name, never with its arguments. See Privacy and telemetry; grasp telemetry off stops it.

grasp mcp acts with the run level of access: it can create projects, edit files, start runs and answer approvals. It cannot change plugins, sign-ins or settings, and it cannot delete projects.

Approval requests exist so that a person decides. An agent that calls approve decides in your place. If you do not want that, tell the agent to stop and ask you when a run needs an approval, or start runs with the strict policy and answer in the app.