MCP Server

Quick start

The easiest path is the hosted endpoint — no install, no Node runtime, just a Bearer key on every request. The setup wizard in your dashboard generates per-client snippets, but here's the two-step version:

1. 1

   Create an API key with MCP scopes

   Go to Dashboard → API Access → Connect AI and click Generate MCP key. This creates a key with the recommended scopes (account:read,servers:read,servers:write,billing:read).

   servers:destroy is off by default — the AI should never be one prompt away from terminating your VM. Enable it explicitly in the key creation form only if you need it.

2. 2

   Add the MCP server to your AI client

   For Claude Code:

   claude mcp add --transport http otwa "https://mcp.otwa.cloud/mcp" \
     --header "Authorization: Bearer YOUR_API_KEY"

   For Cursor — add to ~/.cursor/mcp.json:

   {
     "mcpServers": {
       "otwa": {
         "url": "https://mcp.otwa.cloud/mcp",
         "headers": { "Authorization": "Bearer YOUR_API_KEY" }
       }
     }
   }

   Snippets for Claude Desktop, Windsurf, VS Code, Zed, Continue, and OpenCode are generated in the dashboard.

Tool reference

30 tools across seven surfaces. The required scope on each tool is enforced server-side — a key without the scope gets a 403, the AI sees the error and tells you which scope is missing.

Safety model

We assume the AI is well-intentioned but fallible, and we assume your key might be over-scoped or leak. Three independent layers of defence:

1. 1
   Tool-side confirm flags. Destructive tools require confirm: true and iAcknowledgeDataLoss: true — the AI cannot fire-and-forget; the call surfaces in the model's reasoning.
2. 2
   Typo-guard on destroy. otwa_destroy_server requires expectedLabel matching the server's current label. If labels differ — because the AI looked at the wrong server, or you renamed it mid-conversation — the call is rejected before reaching the API.
3. 3
   Server-side scope enforcement. The servers:destroy scope is split from servers:write. A key without servers:destroy cannot terminate or reinstall — full stop, at the API. Tool guards can be bypassed by a misaligned model; this one can't.

otwa_create_server and otwa_reinstall_server also auto-attach a fresh Idempotency-Key on every retry, so transient network blips never produce two servers or charge twice.

OAuth 2.0 device-code flow

For AI clients that natively speak the MCP authorization spec — no key copy-paste, browser-approved access, revocable from the dashboard. Both Bearer API keys and OAuth tokens are accepted on the same endpoints — the choice is per-client.

1. 1
   Discovery. Spec-compliant client fetches the protected-resource metadata above, then the AS metadata. Both are public, no auth.
2. 2
   Register. POST /api/oauth/register with {client_name, software_id, scope}. RFC 7591 Dynamic Client Registration — no auth, public clients only (no client secret).
3. 3
   Device authorization. POST /api/oauth/device/code returns a user_code like XXXX-YYYY + verification_uri. Open the URI in a browser, sign in, approve the requested scopes.
4. 4
   Token exchange. Poll POST /api/oauth/token at the returned interval. Returns authorization_pending until approved, then {access_token, expires_in, scope}. Use the access token inAuthorization: Bearer otwa_at_….
5. 5
   Refresh proactively. When the access token nears expiry, exchange the refresh token at the same endpoint: grant_type=refresh_token. Returns a fresh access + refresh pair. The old refresh token is single-use — replaying it fails with invalid_grant.
6. 6
   Revoke any time. User-facing list at Dashboard → API access → OAuth grants — one click revoke per token. RFC 7009 endpoint at POST /api/oauth/revoke accepts both access and refresh tokens.

Today most AI clients still expect a pasted Bearer key. Use OAuth if your client supports it; the dashboard's Connect AI wizard still ships per-client key-paste snippets, which work alongside OAuth on the same endpoint.

Local stdio (alternative)

If you'd rather not depend on mcp.otwa.cloud — offline work, auditable local execution, or air-gapped policy — install the npm package and let your AI client spawn it as a stdio child process:

npx -y @otwa/mcp-server

Same tool set, same safety guards. The only difference is the network path: stdio talks directly to api.otwa.cloud without going through us. Source is open and MIT-licensed on GitHub .