openinterp-mcp
v0.1.0 beta · API may shift before v1.0
MCP server + Colab backend for mechanistic interpretability research. Bring your own agent. Works with Claude Code, Cursor, Cline, OpenHands, Aider, or any harness that speaks MCP. Privacy-first. We do not host inference. We do not custody your keys. Your Colab session, your model, your data.
What this is
A research toolkit that turns probe-causality and SAE-feature experiments into agent-callable primitives. Researchers run the model on their own compute (Colab Pro recommended), expose an HTTPS endpoint over ngrok, and let an LLM agent drive experiments via 8 typed MCP tools.
The 8 MCP primitives:
| Tool | What it does |
|---|---|
colab_attach |
Attach to a running Colab/vast.ai/runpod session via its public HTTPS URL. Validates /health, caches the endpoint locally. |
colab_status |
Health check — loaded model, probes in memory, captures held. |
list_probes |
List probes currently loaded in the backend (model_id, layer, position, source). |
capture_acts |
Run a forward pass with hooks, extract activations at specified layers/positions. Returns capture_id. |
probe_eval |
Apply a loaded probe to a stored capture, return AUROC + per-sample scores. |
steer |
Inject direction×α at layer L. Returns base + steered generation + control-token-normalized Δrel (paper-6 protocol). |
sae_lookup |
Decompose a stored activation into top-K SAE features with auto-interp descriptions. |
causality_protocol |
Run the three mandatory checks (random-feature baseline, control-token norm, structural-rigidity α-sweep) and emit a verdict in {causal, weak-causal, epiphenomenal-softmax, epiphenomenal-template, undetermined}. |
Publish + judge primitives are Python modules, not MCP tools. Use
from openinterp_mcp.publish import publishto submit to the Atlas (HF Dataset + Zenodo DOI + registry PR), andfrom openinterp_mcp.judge import reproducefor Claude-Code-as-judge replication. These run outside the MCP request/response loop because they take minutes (long-running side effects).
Architecture (privacy-first)
USER'S MACHINE (laptop) USER'S COMPUTE (Colab/vast.ai/runpod)
├── Claude Code / Cursor / Cline ├── Colab Secrets (HF/OAI/Anthropic keys)
├── openinterp-mcp (stateless) ├── FastAPI + 8 endpoints
└── ~/.openinterp/sessions.json ├── Qwen3.6-27B + probes loaded
(URLs cached, no secrets) └── ngrok / cloudflared tunnel
│
←── HTTPS (ngrok URL) ──────┘
DOES NOT EXIST ANYWHERE:
✗ api.openinterp.org inference endpoint
✗ a server custodying your keys
✗ telemetry / logs traversing our infra
✗ a database of your queries
Quick start (researchers)
1. In a Colab notebook (one cell)
%pip install openinterp-mcp[colab] -q
from google.colab import userdata
import os
for k in ['HF_TOKEN', 'OPENAI_API_KEY', 'ANTHROPIC_API_KEY', 'NGROK_AUTHTOKEN']:
try: os.environ[k] = userdata.get(k)
except: pass
from openinterp_mcp.colab import launch
url = launch(model="Qwen/Qwen2.5-7B-Instruct")
print(f"\n✓ OpenInterp session ready.\n Paste in Claude: /colab-attach {url}\n")
2. In Claude Code / Cursor / Cline
/colab-attach https://abc123.ngrok-free.app
✓ Connected. Qwen2.5-7B loaded. 5 probes available.
/capture-acts "Solve x^2 = 4" --layers L11,L20,L27 --positions end_question
/probe-eval saturation-direction-L20 --acts last_capture
/causality-protocol L20_pre_tool
Install (agent-side)
pip install openinterp-mcp
Add to claude_desktop_config.json (or equivalent for Cursor/Cline):
{
"mcpServers": {
"openinterp": {
"command": "openinterp-mcp",
"args": ["serve"]
}
}
}
Status
v0.0.1 alpha — Phase 1 of an 11-phase build documented at openinterp.org/mcp. Track progress at github.com/OpenInterpretability/openinterp-mcp/issues.
License
Apache-2.0. See LICENSE.
Metadata
Release files for openinterp-mcp 0.2.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| openinterp_mcp-0.2.0.tar.gz | 48.8 kB | Without provenance | Details for openinterp_mcp-0.2.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| openinterp_mcp-0.2.0-py3-none-any.whl | Python 3 | none | any | Details for openinterp_mcp-0.2.0-py3-none-any.whl |
Total release size: 108.4 kB
Release files / openinterp_mcp-0.2.0.tar.gz
| Download URL | openinterp_mcp-0.2.0.tar.gz |
|---|---|
| Size | 48.8 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
84f470ec89ece8922880a012dbca5cad75bacdc8c89eee4df52658c0640a8a48
|
|
BLAKE2b-256 checksum How to use checksums |
3d19a3a3378ae97401cd98b889334faa38693be5a4ce32e43b91aaf47482c620
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.9.6
|
Release files / openinterp_mcp-0.2.0-py3-none-any.whl
| Download URL | openinterp_mcp-0.2.0-py3-none-any.whl |
|---|---|
| Size | 59.6 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
edd6ae9a91df35456a1dff4d6ba9d4ed12c1a7ec41937cadb2628bbbd7ef7d4a
|
|
BLAKE2b-256 checksum How to use checksums |
b373da2f549a58fde2174a013bb9cead0bea155fbc5b1e84d62ae844e05a8521
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.9.6
|
Security for openinterp-mcp 0.2.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.