MCP Server

The Ovrin MCP server exposes sandboxes as tools to any MCP-capable client — Claude Desktop, Claude Code, Cursor, VS Code, and others. The model can create a sandbox, run shell commands, execute stateful code, and read and write files, without you wiring up an SDK.

It is a thin tool layer over the ovrin SDK, so accounts, quota, and metering all apply.

Install

Run it without installing, straight from PyPI:

uvx ovrin-mcp

Or install it into an environment:

pip install ovrin-mcp

Create a scoped key

In the console, create a key on the API keys page with the sandboxes scope. A scoped key can only touch /sandboxes/*, so a leaked client config cannot read your usage, mint keys, or touch billing. See API Keys & Scopes.

export OVRIN_API_KEY="ovrin_..."

Configure your client

Claude Desktop / Claude Code

{
  "mcpServers": {
    "ovrin": {
      "command": "uvx",
      "args": ["ovrin-mcp"],
      "env": { "OVRIN_API_KEY": "ovrin_..." }
    }
  }
}

Cursor / VS Code

{
  "mcpServers": {
    "ovrin": {
      "command": "uvx",
      "args": ["ovrin-mcp"],
      "env": { "OVRIN_API_KEY": "ovrin_..." }
    }
  }
}

Restart the client and the Ovrin tools appear.

Remote transport

stdio (above) runs the server on the client's machine. To share one server across clients or machines, run it over HTTP and point the client at the URL:

ovrin-mcp --transport streamable-http --host 0.0.0.0 --port 8000
# MCP endpoint: http://<server>:8000/mcp

ovrin-mcp --transport sse --host 0.0.0.0 --port 8000
# SSE endpoint:  http://<server>:8000/sse

Terminate TLS and require authentication at the proxy before exposing it — the process holds your API key and can create compute on your account.

Tools

Tool	Purpose
sandbox_create	Create a sandbox (template, timeout, payments)
sandbox_list / sandbox_get	Inspect sandboxes
sandbox_kill	Terminate and stop billing
sandbox_pause / sandbox_resume / sandbox_renew	Lifecycle
command_run	Run a shell command
code_run / create_code_context	Stateful code execution — variables survive between calls
file_read / file_write / file_list / file_search	Files
sandbox_endpoint	The public URL for a port the sandbox serves

A typical agent session: sandbox_create → file_write a script → command_run it → read the output → sandbox_kill.

Options

ovrin-mcp --help

Flag	Default	Purpose
--api-key	OVRIN_API_KEY	API key
--base-url	OVRIN_BASE_URL / https://api.ovrin.app	Control plane URL
--transport	stdio	stdio, sse, or streamable-http
--host / --port	127.0.0.1 / 8000	Bind for the HTTP transports
--default-template	python	Template when sandbox_create omits one
--default-timeout	3600	Lifetime in seconds when omitted
--max-sandboxes	5	Session cap
--keep-sandboxes	off	Do not terminate session sandboxes on exit

Cost and safety

• Session cap. At most --max-sandboxes (default 5) can be created per session; further creates are refused until one is killed.
• Cleanup on exit. When the client disconnects, the server terminates the sandboxes it created this session. --keep-sandboxes disables that. Sandboxes you created through other clients are never touched.
• Scoped key. Use a sandboxes-scoped, expiring key so the MCP process holds the least privilege it needs.
• Prompt injection. A model driving these tools can create compute on your account. Keep the plan's concurrency limit meaningful, and review what the agent did in the console's Sandboxes page.