Metadata-Version: 2.5
Name: ovrin-mcp
Version: 0.1.0
Summary: MCP server for the Ovrin agent compute cloud.
Project-URL: Homepage, https://ovrin.app
Project-URL: Repository, https://github.com/joshluberisse/OvrinPlatform
Project-URL: Documentation, https://docs.ovrin.app/guides/mcp
Author: Neuromorph Systems, LLC
License-Expression: MIT
License-File: LICENSE
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Typing :: Typed
Requires-Python: >=3.10
Requires-Dist: httpx>=0.27
Requires-Dist: mcp>=2
Requires-Dist: ovrin<0.2,>=0.1
Description-Content-Type: text/markdown

# Ovrin MCP server

<!-- mcp-name: io.github.joshluberisse/ovrin-mcp -->

An [MCP](https://modelcontextprotocol.io) server that gives MCP-capable clients
(Claude Desktop, Claude Code, Cursor, VS Code, …) a real Linux computer on
Ovrin: create a sandbox, run shell commands, execute stateful code, and read and
write files — from the model.

It is a thin tool layer over the [`ovrin`](https://pypi.org/project/ovrin/)
Python SDK, so accounts, quota, and metering all apply.

## Install

```bash
pip install ovrin-mcp
```

## Configure

Create a **`sandboxes`-scoped** API key in the console (Keys → Create key). A
scoped key can only touch `/sandboxes/*`, so a leaked client config cannot read
usage, mint keys, or touch billing.

```bash
export OVRIN_API_KEY="ovrin_..."
```

### Claude Desktop / Claude Code

```json
{
  "mcpServers": {
    "ovrin": {
      "command": "ovrin-mcp",
      "env": { "OVRIN_API_KEY": "ovrin_..." }
    }
  }
}
```

Cursor and VS Code use the same `command` + `env` shape.

## 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 |
| `file_read` / `file_write` / `file_list` / `file_search` | Files |
| `sandbox_endpoint` | Public URL for a port |

## Options

```
ovrin-mcp --help
  --api-key            Ovrin API key (default: OVRIN_API_KEY)
  --base-url           Control plane URL (default: OVRIN_BASE_URL)
  --transport          stdio (default) | sse | streamable-http
  --host               Bind host for sse/streamable-http (default: 127.0.0.1)
  --port               Bind port for sse/streamable-http (default: 8000)
  --default-template   Template when sandbox_create omits one (default: python)
  --default-timeout    Lifetime in seconds when omitted (default: 3600)
  --max-sandboxes      Session cap (default: 5)
  --keep-sandboxes     Do not terminate session-created sandboxes on exit
```

## Remote transport

`stdio` is the default and what local clients use. To serve multiple clients
over the network, run the HTTP transports:

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

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

Put it behind TLS and an authenticating proxy before exposing it. Each session
still holds one `OVRIN_API_KEY` (the process key), and the session cap and
cleanup-on-exit apply per process.

On exit the server terminates the sandboxes it created this session
(`--keep-sandboxes` disables that). Sandboxes you created elsewhere are left
alone.
