> ## 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 computer, drive its browser, run shell commands, and read the screen back.

Tools are generated from the published API specification, so the tool list follows the spec rather than the installed server version.

## Connect with OAuth

For clients that support remote HTTP MCP servers, add `https://www.orgo.ai/mcp`. Your client opens Orgo's sign-in and consent page. Choose the workspace to authorize, then approve access. No API key is needed for this connection.

The hosted server supports the OAuth authorization-code flow with PKCE (S256), one-hour access tokens, and rotating refresh tokens. The grant is scoped to the selected workspace. It can create and manage computers, screens, and files in that workspace and read the workspace itself. Calls outside that surface, such as most Templates tools or creating and deleting workspaces, fail over an OAuth connection with `This MCP connection can only manage computers in its workspace.` Use an API key for those.

Manage or revoke connections under **Connected apps** in [Settings → Credentials](https://www.orgo.ai/settings/credentials).

Clients that let you set request headers can also call `https://www.orgo.ai/mcp` with an API key in `Authorization: Bearer $ORGO_API_KEY` instead of OAuth. An API key reaches every tool its scope allows.

## Install locally with an API key

<CodeGroup>
  ```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_..." }
      }
    }
  }
  ```
</CodeGroup>

Get a key at [Settings → Credentials](https://www.orgo.ai/settings/credentials), 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.

<Tip>
  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.
</Tip>

## 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 orgo computer and show me what failed
```

The first prompt runs `orgo_create_computer`, then `orgo_execute_bash`, then `orgo_get_screenshot`. By default `orgo_get_screenshot` returns a link to the stored capture. Pass `response_format: "base64"` and the screenshot comes back as an image the model can see.

## Tools

One tool per API operation, named after its `operationId`. `createComputer` becomes `orgo_create_computer`.

| Group | | Tools |
| - | - | - |
| Workspaces | 5 | `list_workspaces` `create_workspace` `get_workspace` `update_workspace` `delete_workspace` |
| Computers | 11 | `create_computer` `get_computer` `update_computer` `delete_computer` `clone_computer` `fork_computer` `resize_computer` `get_resize_limits` `move_computer` `get_vnc_password` `apply_computer_secrets` |
| Computer Lifecycle | 4 | `start_computer` `stop_computer` `restart_computer` `get_computer_operation` |
| Computer Actions | 10 | `get_screenshot` `mouse_click` `mouse_move` `mouse_drag` `type_text` `press_key` `scroll` `wait` `execute_bash` `execute_python` |
| Screens | 5 | `list_screens` `create_screen` `get_screen` `resize_screen` `destroy_screen` |
| Files | 5 | `upload_file` `list_files` `export_file` `download_file` `delete_file` |
| Templates | 15 | `list_templates` `publish_template` `build_template` and 12 more |
| Account | 3 | `get_account_capacity` `add_account_capacity` `reduce_account_capacity` |

<Accordion title="All 15 Templates tools">
  `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`
</Accordion>

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 `GET` tools. |
| `ORGO_TAGS` | all | Comma-separated spec tags to expose. Two 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. |

<Accordion title="Escape hatches">
  | Variable | Default | Description |
  | - | - | - |
  | `ORGO_PROFILE` | `current` in `credentials.json`, else `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. |
</Accordion>

## Security

<Warning>
  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 → Credentials](https://www.orgo.ai/settings/credentials), or set
  `ORGO_READ_ONLY=true` to register only the read tools.
</Warning>

## 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: `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 `GET`, `PUT` and `DELETE` requests. `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] 58 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.

<AccordionGroup>
  <Accordion title="spawn npx ENOENT on Windows">
    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_..." }
        }
      }
    }
    ```
  </Accordion>

  <Accordion title="HTTP 401: Invalid API key">
    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.
  </Accordion>

  <Accordion title="The tools don't appear in my client">
    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.
  </Accordion>
</AccordionGroup>

## Next steps

<CardGroup cols={2}>
  <Card title="API Reference" icon="code" href="/api-reference/introduction">
    The same operations, with full request and response schemas.
  </Card>

  <Card title="CLI" icon="terminal" href="/guides/cli">
    Drive the same computers from your own terminal.
  </Card>

  <Card title="Claude Code skill" icon="robot" href="/guides/skill">
    Teach Claude when to reach for a computer in the first place.
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.