OMCP R Sandbox Server

A secure, MCP-compliant R code execution environment specialised for OMOP CDM and DARWIN EU® analytics. This server implements the Model Context Protocol (MCP) for safe, isolated, and stateful R session management.

🌟 Key Features

• OMOP/DARWIN Specialised: Pre-configured with OHDSI HADES and DARWIN R packages (CDMConnector, DatabaseConnector, SqlRender, etc.) and Java 17.
• Persistent R Sessions: Maintain state across multiple code executions using Docker-based Rserve containers.
• Robust Output Capturing: Captures stdout and stderr (e.g., print(), summary(), and OHDSI logs) and returns them alongside execution results.
• Per-Execution Limits: execute_in_session supports typed limits (time and output-size controls) for safer runtime behavior.
• Persistent Workspaces: Support for host bind-mounts to preserve files across session lifecycles.
• File Management: Built-in tools to upload cohort definitions, list sandbox files, and retrieve analysis results.
• Structured Errors: Tool failures return machine-readable error objects (code, message, retryable, details).
• Enterprise-Grade Security:
  • Docker isolation with non-root user (UID 1000).
  • Read-only root filesystem with limited writable tmpfs.
  • Dropped Linux capabilities and no privilege escalation.
  • Network isolation (configurable) and resource limits (CPU/Memory).
• Standardised Connectivity: Ready for PostgreSQL/OMOP CDM databases with auto-proxying for localhost connections to host.docker.internal.

🛠️ MCP Tools

The server exposes the following tools to any MCP client:

Tool	Description
create_session	Start a new persistent R session (Docker container).
execute_in_session	Run R code in a session. State persists and output is captured.
list_sessions	List all active R sessions and their metadata.
close_session	Safely stop and remove an R session.
list_session_files	List files in the session's workspace.
read_session_file	Read the content of a file (e.g., analysis results).
write_session_file	Upload a file to the sandbox (e.g., JSON cohort).
install_package	Install R packages dynamically from CRAN or GitHub.

🚀 Quick Start

Prerequisites

• Docker and Docker Compose
• Python 3.10+
• uv (recommended for Python dependency management)

1. Installation

git clone [https://github.com/fastomop/omcp_r]
cd omcp_r
uv pip install -e .

2. Environment Setup

Copy sample.env to .env and configure your database and Docker settings:

DOCKER_IMAGE=omcp-r-sandbox:latest
SANDBOX_TIMEOUT=300
DB_HOST=your-postgres-host
DB_NAME=cdm_database
# ... see sample.env for all options

Example execution with limits:

{
  "session_id": "your-session-id",
  "code": "print('hello')",
  "limits": {
    "max_duration_secs": 5,
    "max_output_bytes": 20000
  }
}

3. Build & Run

Use Docker Compose to build the specialized R sandbox image and start the MCP server:

docker-compose up --build

📖 Documentation

For detailed guides, please refer to the docs/ directory:

• Architecture Overview
• API Reference
• Implementation Details
• Security Model
• Configuration Guide
• Deployment Guide

⚖️ License

MIT