Code Box

⭐ If you find this project useful, please consider giving it a star! ⭐

Overview

Code Box is a self-hosted, production-grade replacement for Azure Assistants Code Interpreter. It delivers the same stateful code execution experience — persistent kernels, file I/O, artifact generation — without being locked into the Azure OpenAI Assistants API or paying per-token execution costs.

Built on Open Interpreter and exposed via the Model Context Protocol (MCP), Code Box runs on any infrastructure (your laptop, a VM, Azure Web App, a container) and plugs into any MCP-compatible agent framework: Semantic Kernel, LangGraph, CrewAI, AutoGen, or your own custom client.

Why Code Box over Azure Code Interpreter?

Key Capabilities

Architecture

Design Principles

• One interpreter per session — complete isolation; no state bleeds across sessions.

• Zero LLM dependency — the server executes code directly via Open Interpreter's runtime. Your agent chooses the model; Code Box just runs the code.

• Stateless HTTP transport — every request is independent, making it fully compatible with Azure Web App reverse proxies, load balancers, and containers.

• Client config clamping — effective = min(client_value, server_max) ensures server-configured safety limits can never be exceeded by any client.

Prerequisites

Quick Start

1. Clone & set up the environment

cd CodeBoxMCP

# Create and activate a virtual environment
python -m venv .venv

# Windows
.venv\Scripts\activate

# Linux / macOS
source .venv/bin/activate

# Install dependencies
pip install -r requirements.txt

2. Configure environment variables

Create a .env file in the project root:

# ─── Server ───
MCP_SERVER_NAME=Code Interpreter MCP
MCP_HOST=0.0.0.0
MCP_PORT=8000

# ─── Session Lifecycle ───
SESSION_TTL=3600
IDLE_TIMEOUT=1800
EXEC_TIMEOUT=300

# ─── Azure Blob Storage (optional) ───
AZURE_BLOB_CONNECTION_STRING=<your-connection-string>
AZURE_BLOB_CONTAINER_NAME=code-interpreter-artifacts
BLOB_SAS_EXPIRY_HOURS=24

# ─── Azure SQL Database (optional) ───
AZURE_DATABASE_CONNECTION_STRING=<your-odbc-connection-string>
AZURE_DATABASE_PASSWORD=<your-password>

3. Start the server

# Option A — module
python -m codebox

# Option B — script
python server.py

# Option C — shell (Linux/macOS)
bash run.sh

On success the server logs:

============================================================
  Code Interpreter MCP
  Transport : streamable-http
  Endpoint  : http://localhost:8000/mcp
============================================================

MCP Tools Reference

Code Box exposes 7 tools via MCP. All accept and return JSON.

exec_code

Execute code in a stateful interpreter session. State persists within the same session_id — variables, imports, DataFrames all survive across calls. Don't re-import or re-load what's already in memory; reference existing variables directly.

Parameters:
  session_id  (string, required)  — Unique session identifier; auto-created on first use.
  language    (string, required)  — e.g. "python"
  code        (string, required)  — The code to execute.

Generated files (plots, CSVs, etc.) are automatically detected as artifacts. If Azure Blob is configured, each artifact gets a SAS URL in the response (new_artifacts[].sas_url).

exec_sql

Run a read-only SQL query with two-level safety:

1. Application layer — keyword blocking (rejects INSERT, UPDATE, DELETE, DROP, etc.).

2. Database layer — always-rollback transaction; no writes can ever persist.

Small results (≤ SQL_MAX_INLINE_ROWS, default 30) are returned inline as JSON. Large results are saved as CSV in input/ — load directly with pd.read_csv(path), no re-upload needed.

upload_file

Download a file from a URL (public or SAS) into the session's input/ folder. Use the returned saved_path in subsequent exec_code calls. Respects MAX_DOWNLOAD_SIZE (default 500 MB) and DOWNLOAD_TIMEOUT (default 120 s).

list_artifacts

Returns metadata for every artifact in the session's output/ directory (filename, path, extension, size, optional SAS URL).

session_info

Returns the session's working directory paths (workdir, input_dir, output_dir) and effective configuration. Recommended as the first call so the agent discovers absolute paths before writing or reading files.

list_sessions

Returns all active sessions with age_seconds, idle_seconds, and workdir.

destroy_session

Explicitly destroys a session — kills the interpreter process and deletes all session files. Call this when the agent is done to release resources.

Session Lifecycle

Sessions are auto-created on first use — just pass any session_id and go. No explicit "create" step required.

First call with session_id          Subsequent calls (same ID)
         │                                    │
         ▼                                    ▼
  ┌──────────────┐                   ┌──────────────┐
  │ Auto-Create  │                   │ Reuse Session│
  │ • New kernel │                   │ • State kept │
  │ • Filesystem │                   │ • Timer reset│
  └──────────────┘                   └──────────────┘
         │                                    │
         └──────── Expires or Destroyed ──────┘
                          │
                          ▼
                  ┌──────────────┐
                  │   Cleaned Up │
                  │ • Process killed │
                  │ • Files deleted  │
                  └──────────────┘

• TTL & idle timeout — sessions expire after SESSION_TTL seconds total or IDLE_TIMEOUT seconds of inactivity.

• Cleanup loop — a background thread reaps expired sessions every CLEANUP_INTERVAL seconds.

• Session recovery — if a session is not found (expired/cleaned up), create a new one with the same session_id and re-upload files / re-run setup. Do not assume prior state survived.

Best Practices

1. First call: session_info to discover absolute paths, then import libraries + load data.

2. Next calls: reuse variables already in memory — don't re-import or re-load.

3. Save outputs to output/ using absolute paths — they become artifacts automatically.

4. Check new_artifacts in exec_code responses for file paths and SAS URLs.

5. Use exec_sql for SQL queries — results land directly in the session, no extra code needed.

6. On error, fix only the broken line — don't re-run everything from scratch.

7. Call destroy_session when done to free interpreter processes and disk space.

Client HTTP Headers

Clients can override server defaults on a per-request basis via HTTP headers. Values are clamped against server maximums.

Connecting from Agent Frameworks

Code Box works with any MCP-compatible client. Here are quick-start snippets for popular frameworks:

Semantic Kernel (Python)

from semantic_kernel.connectors.mcp import MCPStreamableHttpPlugin

plugin = MCPStreamableHttpPlugin(
    name="code_box",
    url="http://localhost:8000/mcp",
)
kernel.add_plugin(plugin)

LangGraph / LangChain

from langchain_mcp_adapters.client import MultiServerMCPClient

async with MultiServerMCPClient({
    "code_box": {
        "url": "http://localhost:8000/mcp",
        "transport": "streamable_http",
    }
}) as client:
    tools = client.get_tools()

CrewAI

from crewai import Agent
from crewai_tools import MCPServerAdapter

with MCPServerAdapter(
    server_params={"url": "http://localhost:8000/mcp", "transport": "streamable_http"}
) as tools:
    agent = Agent(role="analyst", tools=tools.tools)

AutoGen

from autogen_ext.tools.mcp import SseServerParams, mcp_server_tools

tools = await mcp_server_tools(SseServerParams(url="http://localhost:8000/mcp"))
agent = AssistantAgent("analyst", tools=tools)

Project Structure

CodeBoxMCP/
├── server.py                  # Thin launcher (delegates to codebox.server)
├── run.sh                     # Shell launcher (Linux/macOS)
├── requirements.txt           # Python dependencies
├── .env                       # Environment configuration (create this)
├── DOCUMENTATION.md           # Full integration & usage guide
├── USAGE_GUIDE.html           # HTML usage guide
├── architecture.drawio        # Architecture diagram (draw.io)
├── codebox/
│   ├── __init__.py            # Package metadata & version
│   ├── __main__.py            # `python -m codebox` entry point
│   ├── config.py              # Centralised configuration (env vars)
│   ├── server.py              # FastMCP server, tool definitions, entrypoint
│   ├── session_manager.py     # Session lifecycle & interpreter management
│   ├── db_manager.py          # Azure SQL query execution & safety
│   ├── helpers.py             # Blob storage, artifact detection, downloads
│   └── resources.py           # Embedded usage guide resource
└── sessions/                  # Runtime session filesystems (auto-created)

Configuration Reference

All settings are configurable via environment variables or a .env file.

See DOCUMENTATION.md for the full reference including Azure Blob and SQL settings.

Security

• No LLM at the server — code is executed directly; the server never makes model API calls.

• SQL safety — two-level protection: keyword blocking + always-rollback transactions.

• Session isolation — each session runs in its own interpreter process with an isolated filesystem.

• Config clamping — client-supplied values can never exceed server-configured maximums.

• Blob SAS URLs — time-limited, read-only access tokens for artifact downloads.

License

Proprietary — Open Source. See source file headers for the full license notice. Authorized use only.