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.

There are two ways to use it:

• Connect an app to Ovrin's hosted connector. You sign in and choose what the app may do; there is no key to paste. See Connect an app.
• Run the server yourself with an API key, below. It has every template, longer lifetimes and the options at the end of this page.

Connect an app

Apps that take a remote MCP server, such as Claude, ChatGPT and several IDEs, can connect to Ovrin's hosted connector:

https://mcp.ovrin.app/mcp

A self-hosted deployment has its own address, shown on the console's Connect page when it runs a connector. The /capabilities endpoint reports it as public_mcp_connector.

A client that runs in a web page can connect as well. The connector answers requests from any origin, and each one still needs the token you approved.

1. Add the address in the app as a remote MCP server (some apps call it a custom connector).
2. The app opens Ovrin in your browser. Sign in, or create an account.
3. Ovrin shows which app is asking and the address it will send your answer to. Choose what it may do, then Allow.

Ovrin checks every call itself, whatever the app asked you:

Permission	What it allows
sandbox:read	See the sandboxes it created, and read their files
sandbox:create	Create sandboxes, within the limits below
sandbox:exec	Run commands and code, and write files, in its sandboxes
sandbox:manage	Renew, pause, resume and delete its sandboxes

What a connected app can reach:

• Only its own sandboxes. It cannot see or touch sandboxes you created with the API, the console or another app.
• Three at a time, counted across every app connected to your account. Each lasts 30 minutes unless the app asks for less or more. Two hours from creation is the most, renewals included.
• Two minutes per command. A command or code run is stopped at 120 seconds.
• Compute templates only: python, node, code-interpreter and playwright.
• Output of up to 64 KB per call. A result cut short says so.
• No payments, secrets, environment variables or port endpoints.

Your plan's limits and billing apply as usual. To cut an app off, use Connected apps on the console's Account page; it stops working at once. Sandboxes it had running keep going until they expire, two hours at most; delete them from the Sandboxes page if you want them gone sooner.

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.