Overview#
@spineos/mcp@0.1.0 ships 18 tools, grouped by area. Every tool requires a specific capability on the API key that spineos-mcp is using.
When spineos-mcp starts, it calls /v1/me to read the capabilities attached to your key. It then registers only the tools whose required capability is on the key. Tools you cannot use never appear in the assistant's tool list. This keeps the model's prompt surface small and prevents the assistant from picking a tool that would only fail with a 403.
If you change capabilities (by revoking the key and creating a new one with a different scope set), restart your MCP client so it relaunches spineos-mcp and re-reads /v1/me.
Desktops -- read#
| Tool | Required scope | What it does |
|---|
desktops_list | desktop:read | List all desktops owned by the authenticated user. |
desktops_get | desktop:read | Get full details of a single desktop by id. |
Desktops -- lifecycle#
| Tool | Required scope | What it does |
|---|
desktops_start | desktop:lifecycle | Start (or resume) a stopped desktop. |
desktops_stop | desktop:lifecycle | Gracefully stop a running desktop. State and disk preserved. |
desktops_restart | desktop:lifecycle | Restart a running desktop. |
Desktops -- run and capture#
| Tool | Required scope | What it does |
|---|
desktop_exec_python | desktop:control | Run Python code on the desktop's agent runtime. Returns stdout, stderr, and exit code. |
desktop_screenshot | desktop:control | Take a screenshot of the desktop. Returns a PNG image. |
Desktops -- computer control#
| Tool | Required scope | What it does |
|---|
desktop_click | desktop:control | Click at coordinates. |
desktop_type | desktop:control | Type text. |
desktop_key | desktop:control | Press a keyboard key (xdotool name, for example Return, ctrl+a). |
desktop_scroll | desktop:control | Scroll the view. |
desktop_drag | desktop:control | Mouse drag from a start point to an end point. |
Chat#
| Tool | Required scope | What it does |
|---|
desktop_chat | desktop:chat | Send a message to the AI agent running on a desktop. Returns the assistant response. |
Scheduled jobs -- read#
| Tool | Required scope | What it does |
|---|
scheduled_jobs_list | scheduled_jobs:read | List scheduled jobs, optionally filtered by workspace and/or desktop. |
Scheduled jobs -- write#
| Tool | Required scope | What it does |
|---|
scheduled_jobs_create | scheduled_jobs:write | Create a new scheduled job running a command on a cron schedule. |
scheduled_jobs_run_now | scheduled_jobs:write | Trigger an immediate run of a scheduled job, regardless of its cron schedule. |
Knowledge base -- read#
| Tool | Required scope | What it does |
|---|
kb_search | kb:read | Full-text search the workspace knowledge base. Returns ranked hits with excerpts. |
kb_read_note | kb:read | Read the full content of a single note (by path) from a workspace knowledge base. |
Knowledge base -- write#
| Tool | Required scope | What it does |
|---|
kb_write_note | kb:write | Create or overwrite a markdown note (by path) in a workspace knowledge base. |
Workspaces -- write#
| Tool | Required scope | What it does |
|---|
workspace_create | workspaces:write | Create a new workspace owned by the authenticated user. Seeds the default knowledge-base template. |
Mission Control -- write#
| Tool | Required scope | What it does |
|---|
mission_create_task | mission:write | Create a Mission Control task for the on-desktop AI agent, one-off or scheduled, optionally approval-gated. |
What is coming#
Destructive desktop operations (creating new desktops, destroying existing ones) and admin-only tools are planned for a future release of @spineos/mcp. They are not currently exposed and no date is committed. Until they ship, use the dashboard for create and destroy actions.
For the catalogue of capabilities you can put on a key, see API capabilities.