Orgo MCP Server

Official MCP server for controlling Orgo cloud computers from Claude Code, Claude Desktop, and other Model Context Protocol clients.

Install from GitHub, not npm. The canonical install is npx -y github:nickvasilescu/orgo-mcp — the repo ships prebuilt dist/, so this is a fast registry-style install (no compile step). The npm registry still has the obsolete 3.0.0; do not use npx @orgo-ai/mcp until a 4.x release lands there.

Quick Start

1. Get an Orgo API key

Sign up or log in at orgo.ai, then copy an API key from Settings > API Keys.

2. Add the MCP server

The install path uses the GitHub URL so you get the current 4.x build (compact mode, limit, orgo_doctor, etc.). Pin to a release tag for production stability; omit the #ref to track the main branch.

Claude Code:

# Latest from main (prebuilt — installs in seconds)
claude mcp add orgo -e ORGO_API_KEY=sk_live_YOUR_KEY -- npx -y github:nickvasilescu/orgo-mcp

# Or pin to a release tag
claude mcp add orgo -e ORGO_API_KEY=sk_live_YOUR_KEY -- npx -y github:nickvasilescu/orgo-mcp#v4.1.1

Claude Desktop:

{
 "mcpServers": {
 "orgo": {
 "command": "npx",
 "args": ["-y", "github:nickvasilescu/orgo-mcp"],
 "env": {
 "ORGO_API_KEY": "sk_live_YOUR_KEY"
 }
 }
 }
}

Hosted Streamable HTTP server (Claude Code, Cursor, VS Code, and other clients that support remote MCP over HTTP):

{
 "mcpServers": {
 "orgo": {
 "type": "http",
 "url": "https://orgo-mcp.onrender.com/mcp",
 "headers": {
 "X-Orgo-API-Key": "${ORGO_API_KEY}",
 "X-Orgo-Default-Computer-Id": "your-computer-id"
 }
 }
 }
}

The exact shape varies by client: Cursor omits type (it infers the transport from url), Windsurf names the field serverUrl, and VS Code nests servers under a servers key instead of mcpServers.

Claude Desktop is the exception — claude_desktop_config.json is stdio-only and will not start a type: http entry. To reach the hosted endpoint from Claude Desktop, bridge it with mcp-remote (still a stdio command under mcpServers):

{
 "mcpServers": {
 "orgo": {
 "command": "npx",
 "args": [
 "-y", "mcp-remote",
 "https://orgo-mcp.onrender.com/mcp",
 "--transport", "http-only",
 "--header", "X-Orgo-API-Key:${ORGO_API_KEY}",
 "--header", "X-Orgo-Default-Computer-Id:${ORGO_DEFAULT_COMPUTER_ID}"
 ],
 "env": {
 "ORGO_API_KEY": "sk_live_YOUR_KEY",
 "ORGO_DEFAULT_COMPUTER_ID": "your-computer-id"
 }
 }
 }
}

X-Orgo-Default-Computer-Id is optional: it pins a default computer for this connection so tool calls can omit computer_id (the remote equivalent of the ORGO_DEFAULT_COMPUTER_ID env var, which can't be per-user on a shared host). Clients that only let you configure a URL can pass it as a query param instead: https://orgo-mcp.onrender.com/mcp?computer_id=your-computer-id.

PowerShell users can wrap the Claude Code command because PowerShell may mangle -- when it reaches npm shims:

cmd /c "claude mcp add orgo -e ORGO_API_KEY=sk_live_YOUR_KEY -- npx -y github:nickvasilescu/orgo-mcp"

About the GitHub install. The repo commits prebuilt dist/ and has no prepare script, so npx fetches the repo and installs only the three runtime dependencies — no TypeScript toolchain, no compile. Cold installs take a few seconds; subsequent invocations are cached. CI rejects any commit whose dist/ doesn't match src/, so main is always runnable.

Related MCP server: CUA MCP Server

Tools

The server exposes 28 focused tools.

Each tool is registered with MCP annotations for readOnlyHint, destructiveHint, idempotentHint, and openWorldHint. orgo_restart_computer is marked destructive because it can interrupt running processes and unsaved VM state. Text responses are sanitized before they are returned to the MCP client, so password, token, secret, credential, and API-key fields are redacted even when Orgo API responses include them.

Compact mode for read tools

Read tools (orgo_list_workspaces, orgo_get_workspace, orgo_workspace_by_name, orgo_list_computers, orgo_get_computer, orgo_list_files) are compact by default since 4.1.0: noisy fields like instance_details, template_build_id, and user_id are dropped, keeping id, name, status, timestamps, and key resource fields (cpu, ram, os, disk_size_gb, fly_instance_id, file size/path). Typical savings: 50%+ on list endpoints (a 290 KB workspace list shrinks to ~50 KB). Pass compact: false when you need the complete raw payload. Responses are also no longer pretty-printed — both changes affect default response shape if you upgraded from ≤4.0.x.

Health check (orgo_doctor)

Call orgo_doctor (no arguments) to probe MCP server health: auth source detected (env:ORGO_API_KEY or http_header, never the key value), API reachability with status code, and round-trip latency in ms. Returns { ok, auth, api } — ok: true means both auth is configured and the live Orgo API responded. Use as the first call from an agent harness to verify setup, or after a tool error to distinguish auth failures (status_code: 401) from network issues (no status_code, error: "Cannot reach Orgo API").

Client-side limit for list tools

Pass limit: N (1–500) to orgo_list_workspaces, orgo_list_computers, or orgo_list_files to cap the number of items returned. The Orgo API does not paginate server-side, so the MCP fetches everything and trims client-side. When truncation occurs, the response gains total (the real count) and truncated: true. Omit limit to return everything (current default — backward compatible). Combine with compact: true for the smallest payload: { limit: 5, compact: true } typically returns under 3KB even on accounts with hundreds of computers.

Deliberately not exposed:

• computer start/stop tools

• VNC password access

• account/profile/credits/transactions

• autonomous agent/thread tools

• RTMP streaming tools

• template management tools

Production Safety Controls

Use environment variables to restrict the exposed surface without changing client config.

Examples:

# Observation-only mode
ORGO_READ_ONLY=true npx -y github:nickvasilescu/orgo-mcp

# Browserless VM control without shell access
ORGO_TOOLSETS=core,screen,files npx -y github:nickvasilescu/orgo-mcp

# Keep shell enabled, but remove bash
ORGO_TOOLSETS=shell ORGO_DISABLED_TOOLS=orgo_bash npx -y github:nickvasilescu/orgo-mcp

Read-only mode currently exposes:

orgo_list_workspaces
orgo_get_workspace
orgo_workspace_by_name
orgo_list_computers
orgo_get_computer
orgo_screenshot
orgo_wait
orgo_list_files
orgo_download_file
orgo_doctor

Environment Variables

Self-Hosting

Local stdio:

git clone https://github.com/nickvasilescu/orgo-mcp.git
cd orgo-mcp
npm install
ORGO_API_KEY=sk_live_YOUR_KEY npm start

Local HTTP:

npm install
npm run build
MCP_TRANSPORT=http npm start
curl http://localhost:8000/health

Docker:

docker build -t orgo-mcp .
docker run -p 8000:8000 -e MCP_TRANSPORT=http orgo-mcp

Render:

1. Fork this repo.

2. Create a Render Blueprint from render.yaml.

3. Connect clients to https://YOUR_RENDER_HOST/mcp with an X-Orgo-API-Key header.

The hosted server does not store a shared Orgo key. Each request must include the user's Orgo API key header.

Architecture

npx / stdio:
 MCP client -> stdio -> @orgo-ai/mcp -> Orgo API
 ORGO_API_KEY env var

Hosted HTTP:
 MCP client -> HTTPS -> orgo-mcp server -> Orgo API
 X-Orgo-API-Key header

Shell commands:
 orgo_bash -> Terminal WebSocket primary -> VM
 -> REST /bash fallback -> VM

Development

npm install
npm run build
npm test
npm start

CI runs:

• TypeScript build from a clean dist/

• MCP tool-list smoke tests for default, read-only, toolset, allowlist, and denylist policies

• HTTP transport health and auth smoke tests

• committed-dist/ freshness check (rebuild must produce no diff)

• npm package content checks

• Docker image build

dist/ is committed so the GitHub install needs no build step — after changing src/, run npm run build and commit the regenerated dist/ alongside.

Before publishing:

npm test
npm pack --dry-run

Troubleshooting

Security

• Do not commit .env files or API keys.

• Prefer ORGO_READ_ONLY=true for observation-only clients.

• Disable the shell toolset for clients that should not execute VM commands.

• Treat orgo_bash and orgo_exec as high-power tools: they can modify anything reachable from the target VM.

• HTTP deployments should pass the user's key per request via X-Orgo-API-Key; do not bake a production Orgo key into the server.

License

MIT. See LICENSE.

Maintenance

Resources

• NPM Package
• GitHub Repository
Need Help?Related Servers

Tools

• orgo_ai_completionA
• orgo_bashA
• orgo_clickA
• orgo_create_computerA
• orgo_create_projectA
• orgo_delete_computerA
• orgo_delete_fileA
• orgo_delete_projectA