Skip to main content
Glama
OpenInterpretability

openinterp-mcp

by OpenInterpretability
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python

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 publish to submit to the Atlas (HF Dataset + Zenodo DOI + registry PR), and from openinterp_mcp.judge import reproduce for Claude-Code-as-judge replication. These run outside the MCP request/response loop because they take minutes (long-running side effects).

Related MCP server: CatoBot autoexperiment MCP Server

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.

This server cannot be deployed

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Maintenance

ActivityInactive
ResponsivenessUnresponsive

Resources

Related MCP Connectors

Related MCP Servers