Server URL

https://app.airogeledit.org/api/v1/mcp

Add this URL as a remote MCP server in a client that supports Streamable HTTP and OAuth. The server publishes OAuth authorization and protected-resource metadata, so compatible clients can discover sign-in automatically.

Authorize access

Add the server URL in your MCP client.
Sign in to Airogel Editor when redirected.
Review and approve the requested workspace permissions.
Return to the client and refresh its tool list.

Start with accounts_list

Call accounts_list first. Every other standard tool needs an account_id belonging to the authenticated user.

1. accounts_list
2. projects_list(account_id)
3. scenes_list(account_id, project_id)
4. scene_objects_list(account_id, project_id, scene_id)

Scopes

What a client may do is decided by the scopes you approve when authorizing it. A tool you were not granted the scope for is not merely refused — it is absent from tools/list entirely, so a client connected with read-only scopes advertises a read-only tool set rather than offering writes that then fail.

Scopes are flat: write does not imply read

objects:write does not include objects:read. A client granted only the write scope can create and update objects but cannot list them, which in practice means it cannot find the object it wants to change. Grant both halves of any area you intend to work in.

Scope	What it unlocks
`accounts:read`	`accounts_list`. Required in practice, because every other tool takes an `account_id`.
`projects:read`	`projects_list`, `projects_publish_check`, `projects_publication_status`, `projects_script_diagnostics`
`projects:write`	`projects_create`, `projects_update`, `projects_configure_multiplayer`. It does not include publishing.
`publishing:write`	`projects_publish`, `projects_unpublish` — putting a game on, or taking it off, its public URL. These two also require that you are an admin of the account; a member's connection gets `forbidden`.
`scenes:read`	`scenes_list`, `scenes_take_screenshot`
`scenes:write`	`scenes_create`, `scenes_update`, `scenes_delete`
`objects:read`	`scene_objects_list`, `physics_run_simulation`, and the five `spatial_*` planning tools
`objects:write`	`scene_objects_create`, `scene_objects_update`, `scene_objects_delete`, the two `_batch` variants, `soft_bodies_create`, `soft_bodies_update`, both `vehicles_create_` tools, and `scenes_open_editor_link` (the editor it opens can change objects)
`materials:read` / `materials:write`	`materials_list` / `materials_create`, `materials_update`, `materials_delete`
`shaders:read` / `shaders:write`	`shaders_list` / `shaders_create`, `shaders_update`, `shaders_delete`
`scripts:read` / `scripts:write`	`scripts_list` / `scripts_create`, `scripts_update`, `scripts_delete`
`assets:read`	`assets_list`, `assets_get_generated_recipe`, `assets_get_upload_session`
`assets:write`	`assets_upload_from_url`, `assets_create_upload_session`, `assets_delete`, and the three `assets_generate_*` tools
`support:read` / `support:write`	`support_list`, `support_get` / `support_contact`

Two tools need scopes from more than one area. vehicles_create_wheeled and vehicles_create_tracked require both objects:write and scripts:write, because each one creates a vehicle and the driving script attached to it.

scripting_run_editor_lua is the one tool satisfied by either objects:read or objects:write. Its default inspect mode only reads the scene, so a read-only client can use it; apply mode is checked separately and needs objects:write.

projects_script_diagnostics is likewise satisfied by either projects:read or scripts:read: the errors it reports are in your scripts, but they come from the published project.

A client that does not ask for particular scopes is given mcp, shown on the approval screen as "Create, view, and manage content in your Airogel workspace". It unlocks every tool on this server at once, though publishing still requires an account admin. To connect with less, use a client that lets you choose scopes and request the ones in the table instead.

Two further scopes, admin:debug:read and admin:support:write, apply only to the separate platform-administration server and are not available on this one. mcp does not grant them.

Error codes

Every tool reports failure the same way, as JSON carrying ok: false, a machine-readable error code, and a human-readable message:

{
  "ok": false,
  "error": "insufficient_scope",
  "message": "This tool requires OAuth scope(s): shaders:write"
}

Code	What it means, and what to do
`insufficient_scope`	The token is valid but was not granted a scope this call needs. The message names the missing scopes. Re-authorize the client and approve them; retrying will not help.
`unauthorized`	No authenticated user, or the `account_id` does not belong to the signed-in user. Call `accounts_list` and use an id from that response — an account you can see in a browser is not necessarily one this token can reach.
`forbidden`	Authenticated and in scope, but the tool needs more than a scope. On this server that means `projects_publish` and `projects_unpublish`, which also require that you are an admin of the account; a member's connection gets `forbidden` however the client was authorized. Ask an account admin to publish, or to make you one.
`not_found`	No record with that id in this account. Also what you get for an archived project and for anything inside one, which is deliberate: archiving hides a project from every tool, not just from `projects_list`.
`validation_error`	The call reached the editor and the editor refused the values — a number out of range, a required field missing, a reference to something that does not exist. The message is the editor's own wording and is the thing to read.

A few tools add codes of their own in the same shape. physics_run_simulation, scenes_take_screenshot, and scripting_run_editor_lua return editor_unavailable when no visible editor tab with the matching scene picked the request up in time — open the scene and retry, or open the URL from scenes_open_editor_link in a browser you control — and simulation_failed, screenshot_failed, or editor_script_failed when the tab ran it and it failed. support_contact returns delivery_error if the request could not be sent. projects_script_diagnostics returns not_published for a game that has never been published, and projects_publish refuses with publishing_disabled, preflight_failed, publication_limit_reached, or publish_in_progress — see the MCP tool guide for what each means. Anything else unexpected comes back as error, with the reason in message.

Tool discovery

The MCP tools/list response is the canonical machine-readable reference. It includes the tools currently available to the signed-in user, their descriptions, and typed input schemas. Because availability follows the granted scopes, the list is also the quickest way to confirm what a connection can actually do.

For a written walkthrough of what each tool is for, see the MCP tool guide. If you want an assistant that already knows the editor without connecting a client at all, see the AI assistant.

Upcoming: admin model permission

Pending deployment, the separate platform-administration server at /api/v1/admin/mcp adds admin:models:write for refreshing the model catalog and adding or removing plan model assignments. This scope requires a platform administrator and OAuth authentication. Request it together with admin:debug:read to list plans and models before making changes. Existing connections must authorize the new scope; mcp does not grant it. See the upcoming platform model administration section in the MCP tool guide.