> ## Documentation Index > Fetch the complete documentation index at: https://docs.orgo.ai/llms.txt > Use this file to discover all available pages before exploring further. # MCP > Every Orgo API operation as an MCP tool, generated from the live spec. The Orgo MCP server gives any [Model Context Protocol](https://modelcontextprotocol.io) client direct control of your cloud computers: spin up a Linux desktop, drive its browser, run shell commands, and read the screen back. Its tools are generated from the same `openapi.json` that produces this site's [API Reference](/api-reference/introduction), so the two can never disagree. 43 tools, one per endpoint, over stdio. ## Install ```bash Claude Code theme={null} claude mcp add orgo -e ORGO_API_KEY=sk_live_... -- npx -y orgo-mcp-server ``` ```bash Codex theme={null} codex mcp add orgo --env ORGO_API_KEY=sk_live_... -- npx -y orgo-mcp-server ``` ```json Claude Desktop theme={null} { "mcpServers": { "orgo": { "command": "npx", "args": ["-y", "orgo-mcp-server"], "env": { "ORGO_API_KEY": "sk_live_..." } } } } ``` ```json Cursor theme={null} { "mcpServers": { "orgo": { "command": "npx", "args": ["-y", "orgo-mcp-server"], "env": { "ORGO_API_KEY": "${env:ORGO_API_KEY}" } } } } ``` ```json VS Code theme={null} { "inputs": [ { "type": "promptString", "id": "orgo-key", "description": "Orgo API key", "password": true } ], "servers": { "orgo": { "type": "stdio", "command": "npx", "args": ["-y", "orgo-mcp-server"], "env": { "ORGO_API_KEY": "${input:orgo-key}" } } } } ``` ```json Any MCP client theme={null} { "mcpServers": { "orgo": { "command": "npx", "args": ["-y", "orgo-mcp-server"], "env": { "ORGO_API_KEY": "sk_live_..." } } } } ``` Get a key at [orgo.ai/workspaces](https://www.orgo.ai/workspaces) → Settings → API Keys, then restart your client. Config lives at `~/.cursor/mcp.json` for Cursor, `.vscode/mcp.json` for VS Code, `~/.codeium/windsurf/mcp_config.json` for Windsurf, and `~/Library/Application Support/Claude/claude_desktop_config.json` for Claude Desktop on macOS. Already using the [CLI](/guides/cli)? Run `orgo login` once and drop the `env` block entirely. The server reads the same `~/.orgo/credentials.json`, so your key never has to sit in a config file. ## Try it ```text theme={null} spin up an orgo computer and screenshot the orgo.ai homepage ``` ```text theme={null} open chrome on my orgo computer, search for the weather, screenshot the result ``` ```text theme={null} list my orgo computers and stop the ones that are idle ``` ```text theme={null} run the test suite on a clean linux desktop and show me what failed ``` The first prompt runs `orgo_create_computer`, then `orgo_execute_bash`, then `orgo_get_screenshot`. Screenshots come back as images the model can actually see, not links. ## Tools 43 tools, one per API operation, named after its `operationId`. `createComputer` becomes `orgo_create_computer`. | Group | | Tools | | ------------------ | -- | ------------------------------------------------------------------------------------------------------------------------ | | Workspaces | 4 | `list_workspaces` `create_workspace` `get_workspace` `delete_workspace` | | Computers | 7 | `create_computer` `get_computer` `delete_computer` `clone_computer` `resize_computer` `move_computer` `get_vnc_password` | | Computer Lifecycle | 3 | `start_computer` `stop_computer` `restart_computer` | | Computer Actions | 9 | `get_screenshot` `mouse_click` `mouse_drag` `type_text` `press_key` `scroll` `wait` `execute_bash` `execute_python` | | Files | 5 | `upload_file` `list_files` `export_file` `download_file` `delete_file` | | Templates | 15 | `list_templates` `publish_template` `build_template` and 12 more | `orgo_get_template_schema` `orgo_list_templates` `orgo_publish_template` `orgo_validate_template` `orgo_list_curated_templates` `orgo_list_curated_template_versions` `orgo_list_template_versions` `orgo_get_template` `orgo_delete_template` `orgo_build_template` `orgo_get_build_status` `orgo_cancel_build` `orgo_stream_build_events` `orgo_test_run_template` `orgo_stop_template_run` Group names are the spec's own tags, so `ORGO_TAGS="Workspaces,Computers"` narrows the surface using the same words the [API Reference](/api-reference/introduction) uses. Set it when a client's tool picker starts guessing. ## Configuration Nothing here is required. `ORGO_API_KEY` is the only variable most setups ever set. | Variable | Default | Description | | -------------------------- | ------- | -------------------------------------------------------------------------------------------------------- | | `ORGO_API_KEY` | (none) | Your API key. Falls back to `~/.orgo/credentials.json` from `orgo login`. | | `ORGO_READ_ONLY` | `false` | Any value but `false`, `0`, `no` or `off` registers only the 15 `GET` tools. | | `ORGO_TAGS` | all | Comma-separated spec tags to expose. Three contain a space, so quote it: `"Computers,Computer Actions"`. | | `ORGO_DEFAULT_COMPUTER_ID` | (none) | Pin a computer so action tools can omit `id`. An explicit `id` always wins. | | Variable | Default | Description | | ---------------------- | --------------------------------------------------------------------- | ----------------------------------------------------------------- | | `ORGO_PROFILE` | `default` | Which credential profile to read. | | `ORGO_API_BASE_URL` | `https://www.orgo.ai` | Point at a different host. | | `ORGO_TIMEOUT_MS` | `120000` | Per-request timeout. | | `ORGO_RETRIES` | `2` | Retries for idempotent requests on a 5xx or a dropped connection. | | `ORGO_RAW` | unset | Return exactly what the API sent, without shaping. | | `ORGO_SPEC_URL` | [the published spec](https://docs.orgo.ai/api-reference/openapi.json) | Where to load the spec from. | | `ORGO_SPEC_MAX_AGE_MS` | `86400000` | How long a cached spec stays fresh. | | `XDG_CACHE_HOME` | `~/.cache` | Where the spec cache lives. | ## Security An `sk_live_` key is account-wide by default, and `orgo_execute_bash` and `orgo_execute_python` run arbitrary commands on a live machine. Leave your client's tool confirmation on. For a narrower blast radius, create a workspace-scoped key under Settings → API Keys, or set `ORGO_READ_ONLY=true` to register only the 15 read tools. ## How it works **Tools come from the spec.** Descriptions, types, enums, defaults and required fields are read straight out of it, so `orgo_create_computer` already knows `ram` is one of 4, 8, 16, 32 or 64 without anyone writing that down twice. Path, query and body parameters flatten into one argument list, so a call reads `orgo_resize_computer({ id, mem_gb })` rather than nesting a body. Annotations follow the HTTP method: the 15 `GET` tools are read-only, and every write is marked destructive, because `orgo_execute_bash` cannot promise otherwise. **Responses are shaped to it too.** Only the fields the spec declares survive, which keeps internal state the docs never promise out of the model's context. A schema matching none of the keys in hand is treated as describing something else, so the payload passes through untouched instead of being emptied. Spec drift costs verbosity, never data. Set `ORGO_RAW=1` to turn shaping off. **Failures retry only when that is provably safe.** A 5xx or a dropped connection is retried with doubling backoff, but only for the methods the spec marks idempotent. `orgo_execute_bash` and `orgo_mouse_click` get exactly one attempt, because running either twice is worse than failing once. **The spec is loaded fresh.** In order, first one wins: 1. **Cache** - `$XDG_CACHE_HOME/orgo-mcp/openapi.json`, if fetched within `ORGO_SPEC_MAX_AGE_MS`. 2. **Network** - `ORGO_SPEC_URL`, 5 second timeout, written back to the cache. 3. **Stale cache** - whatever was last fetched. 4. **Bundled snapshot** - shipped in the npm package. A normal start is instant and offline. A start after the cache expires picks up whatever shipped in the API that day. A machine with no network still works. ## Troubleshooting Run the server directly to see what it thinks. It prints one line to stderr, then waits for JSON-RPC on stdin: ```bash theme={null} ORGO_API_KEY=sk_live_... npx -y orgo-mcp-server # [orgo-mcp] 43 tools from Orgo API 2.0.0 (https://docs.orgo.ai/api-reference/openapi.json) → https://www.orgo.ai/api ``` That line names the tool count, the API version and which spec source won, which answers most setup questions on its own. Silence on stdout is correct; that channel carries the protocol. npm ships `npx.cmd`, and Node's `spawn` will not resolve a `.cmd` without a shell. Wrap it: ```json theme={null} { "mcpServers": { "orgo": { "command": "cmd", "args": ["/c", "npx", "-y", "orgo-mcp-server"], "env": { "ORGO_API_KEY": "sk_live_..." } } } } ``` Check the key on its own: ```bash theme={null} curl -H "Authorization: Bearer $ORGO_API_KEY" https://www.orgo.ai/api/workspaces ``` If that works but the server does not, your client is not forwarding `env`. Pass the key inline with `claude mcp add -e` instead. Fully quit and relaunch. Most clients read MCP config only at startup, and Claude Desktop needs a real quit rather than closing the window. Then check `ORGO_READ_ONLY` and `ORGO_TAGS`, which reduce the tool list by design. Claude Desktop logs to `~/Library/Logs/Claude/mcp-server-orgo.log` on macOS. ## Next steps The same 43 operations, with full request and response schemas. Drive the same computers from your own terminal. Teach Claude when to reach for a computer in the first place.