IPi
IPi gives MCP agents persistent IPython kernels, Jupyter notebooks, and durable local output artifacts. It is designed for Codex and Claude Code.
IPi is not an LLM harness. It has no provider client, agent turn loop, terminal UI, prompt manager, or context-window manager. The external harness owns the conversation; IPi owns notebook execution. IPi installs no host hooks.
The PyPI distribution and its command are ipinb; the Python import is ipi. MCP dependencies are included by default.
Run
IPi supports Linux and macOS and requires Python 3.11 or newer plus uv. Run
the published package without installing it permanently:
uvx ipinb
uvx ipinb with no arguments starts a stdio MCP server. Add it to the host's MCP configuration yourself, for example in Codex's .codex/config.toml:
[mcp_servers.ipi]
command = "uvx"
args = ["ipinb@0.7.0"]
or in Claude Code's .mcp.json:
{"mcpServers": {"ipi": {"command": "uvx", "args": ["ipinb@0.7.0"]}}}
Pin an exact version so that every process of one host session runs the same IPi. Do not use uvx ipi: the PyPI name ipi belongs to an unrelated package.
Set IPI_INSTALL_REQUIREMENT to an authenticated requirement when child
kernels must reconstruct a private Git-installed IPi host. The value is used
only at launch and is removed from published runtime state.
Tools And Storage
The same core MCP catalog serves stdio and HTTP:
create_kernel,list_kernels, andclose_kernelmanage explicit kernel resources.ipython(kernel_id, code)accepts Python and observes it for a bounded interval. Calls to one kernel may overlap and share globals.yield_time_ms=0always returns an accepted cell handle.ipdbprovides optional exception inspection and real breakpoint/stepping control. Ordinary failures finish normally, and the transcript header says when their frames are available toipdb.read_cellretrieves Python state and output or Markdown source and metadata, optionally waiting for Python output or completion;interruptrequests cancellation of one cell. Each reader owns its output cursor; cancelling observation does not cancel Python.list_cellsandmarkdowninspect and author retained notebook work.view_image(kernel_id, path)returns one PNG, JPEG, GIF, or WebP file from the kernel's filesystem as MCP image content. Settools.view_image = falseto omit it.
Wait for a predecessor to succeed before submitting dependent code. interrupt is best effort and never escalates to killing a sibling or kernel. close_kernel deliberately discards one kernel's live state while preserving retained records and other kernels. There is no active-kernel selector or agent-facing whole-service shutdown.
For Codex, a kernel created by create_kernel gets CODEX_THREAD_ID from that call's _meta["x-codex-turn-metadata"]["thread_id"], so notebook code and its subprocesses see the same thread as Codex's own shell tools. It is set before bootstrap cells run; kernel plugin callbacks run earlier and do not see it. The prewarm kernel starts without a request and does not get it.
Bash is disabled by default. Set IPI_MCP_ENABLE_BASH_TOOL=1 before startup to expose it; 0 disables it. Optional Bash also requires kernel_id. The ipdb tool requires kernel_id on every call. Add cell_id for execution-specific inspection or control; omit it to configure kernel-wide breakpoints and exception stops. See Debugging.
The notebook skill includes locally readable guides for execution and result recovery, kernel environments and SSH, debugging, and rich output. Agents load the relevant guide when needed. docs/ owns their content; matching copies ship in the skill and package, with packaging checks guarding against drift.
Execution requires an explicit kernel_id. ipython waits up to 10 seconds for a cell to finish (yield_time_ms up to 30,000) and read_cell waits up to 20 seconds more (up to 100,000); both return as soon as the cell finishes. Zero returns an accepted handle for ipython and an immediate read for read_cell. Observation is independent of execution lifetime.
Cell output comes back as plain text in the form of an IPython console transcript, plus image content: a [cell ...] header with state, totals and next start, raw prints and logs, <display ...> blocks for display outputs, Out[n]: for results, and raw tracebacks. Output over max_output_tokens (default 8,000) keeps its head and tail. read_cell(start=...) returns only output after a position; nothing has to be paged or drained. Over stdio, the header also names a private temporary directory with each cell's full output as files. In Codex code mode, print result.content items rather than the whole result. Markdown replies include their source and metadata.
Managed kernels keep IPython history in memory because the notebook and registry are the durable execution record. Kernel creation is explicit, apart from optional discoverable startup prewarming. A closed or lost handle never creates a replacement.
Handles combine a persisted nine-digit decimal registry prefix with k or c and a durable counter, such as 123456789k0 and 123456789c1. Pass them unchanged to their originating registry; IDs are never reused within that registry. ipython, read_cell, ipdb, and bash return text transcripts; the other tools return one compact JSON text with typed resource, handle, inventory, or error envelopes. No tool returns structuredContent, so each fact reaches the model once in every host. Large Markdown sources and individual output events have immutable MCP resource URIs. Use read_cell(..., include_artifact_metadata=True) for the cell's replay export references and SHA-256 checksums.
ipython returns its transcript plus any images the cell displayed as MCP
image content, at most four per result, so plt.show() is one step instead of a
path the model has to fetch. [tools] inline_images = "off" disables that; images past
inline_image_max_px or inline_image_max_bytes are skipped rather than
resized, since IPi carries no imaging dependency.
Each notebook runtime gets a new session. Local sessions are stored under:
<initial-cwd>/.agents/sessions/<session-id>/
session.jsonl
kernels/123456789k1/notebook.ipynb
kernels/123456789k1/outputs/manifest.json
kernels/123456789k1/outputs/c1/g-<sha256-prefix>/input.py
kernels/123456789k1/outputs/c1/g-<sha256-prefix>/o1-stdout.txt
Every input and every retained Jupyter MIME output has a durable local
destination. Output available for the first MCP result is persisted before IPi
builds that bounded response. Returned and recorded paths identify immutable
response-time generations. Yielded and late output publishes a new
generation as it arrives; manifest.json atomically points to the latest
reduced state, including Jupyter clear and display updates. Unfinished cells
are recorded as aborted during shutdown. Kernels and Python state
live until the MCP process exits; IPi does not resume them after restart.
Execution and plugins are trusted local Python, not a sandbox.
Generation directories normally use eight hexadecimal prefix characters and
extend on collision. Their .sha256 file and the manifest retain the complete
digest.
Importing Python Scripts From Paths
Kernels can import toolfuncs, an IPi dependency. toolfuncs.load(path) runs one Python script in the kernel without its __main__ block and returns a namespace of the functions, classes, and other callables that the script defines:
import toolfuncs
tool = toolfuncs.load("/absolute/project/scripts/report.py")
tool.summarize("results.csv")
When the script has PEP 723 metadata, load first installs the dependencies whose distributions are absent from the kernel with uv pip install --python sys.executable. It does not replace a distribution that is already installed; when the installed version does not satisfy the script, load warns and keeps it. This changes the disposable environment of the running kernel, like %pip, and needs uv on the kernel's PATH (on an SSH target too). Loading runs the source inside the kernel process, so review untrusted source and metadata first.
load is not a module import: it runs the script again on each call, returns only the callables, does not register a module in sys.modules, and importlib.reload does not apply. Functions that must be pickled, for example for a process pool, belong in an importable module.
HTTP
Stdio is the primary transport. FastMCP HTTP is also available:
uvx ipinb --transport http --host 127.0.0.1 --port 8000
The process registry owns kernels and cells independently of HTTP transport sessions. Reconnecting clients use the same explicit kernel_id and cell_id; resource IDs are not authentication credentials. Both transports use the same schemas, observation windows, and lifecycle. No server.session_mode setting is needed.
server.running_capacity defaults to eight execution lanes per kernel, server.queue_capacity to 64 waiting submissions, and server.kernel_capacity to eight live or starting kernels. Saturation rejects a new submission before acceptance. The registry retains terminal records indefinitely by default. Set server.registry_root to retain and reopen the same on-disk registry across server restarts; live Python state is reported lost, never reconstructed implicitly. Only one process may own that directory at a time.
Inactive kernels expire after server.kernel_idle_timeout_s (one hour by default; zero disables it). The repeatable -c/--config key=value option overrides strict configuration fields using dotted keys and TOML values.
IPi adds no HTTP authentication: anyone who can reach the port can run code as the server's user. When ipinb binds a loopback address, it rejects requests whose Host or Origin header names another host (FastMCP's host_origin_protection="auto"), so a web page cannot reach the server through DNS rebinding. That protects against browsers, not against other local users on a shared machine, and it does not apply to a non-loopback bind. For those cases, put an authenticating reverse proxy in front, or build your own server on the IPi library with a FastMCP auth= provider (or your own ASGI middleware); with a provider, per-principal scoping separates each authenticated client's kernels and cells. A reverse proxy that forwards the client's Host header (Caddy reverse_proxy, oauth2-proxy pass_host_header, Traefik passHostHeader) gets 421 Misdirected Request from that check, so configure the proxy to send the bound address as Host, or set FASTMCP_HTTP_ALLOWED_HOSTS to the forwarded host name. Code that builds its own server chooses its own Host/Origin policy.
ipinb refuses to start an HTTP transport while any IPI_MCP_HTTP_AUTH_* variable is set, because IPi 0.6 used them for the token authentication that 0.7.0 removed.
Pass --connection-file PATH when another local process needs a machine-readable
endpoint. IPi removes a stale file before startup, waits until the HTTP origin
is accepting requests, and atomically writes a private 0600 JSON manifest:
{
"transport": "http",
"url": "http://127.0.0.1:8000/mcp",
"version": 2
}
The last successfully written manifest remains after shutdown as a diagnostic record; the next launch removes it before starting.
SSH Kernels
create_kernel(cwd=...) accepts either a local absolute path or a per-kernel
SSH URI:
create_kernel(cwd="/Users/me/local-project")
create_kernel(cwd="ssh://gpu-box/opt/projects/model")
create_kernel(cwd="ssh://alice@gpu-box:2222/opt/projects/model")
The URI path is the absolute working directory on the target. Host aliases,
keys, agents, ports, ProxyJump, and host-key policy come from normal OpenSSH
configuration. Authentication is non-interactive: IPi never accepts a password
in the URI, prompts for credentials or host trust, weakens host-key checking, or
forwards the SSH agent. Establish host trust and verify ssh -T <alias> works
before creating the kernel.
Each remote kernel owns a private OpenSSH master, five target-loopback Jupyter
forwards, and a mode-0700 target session under /tmp. IPi resolves the latest
official portable uv release at launch, verifies its publisher checksum on
the host and target, stages the exact running IPi build, and removes the staged
runtime at shutdown. The target project does not need a host mirror and IPi
does not install target system software. The target must provide python3
3.10 or newer for the isolated, standard-library-only session owner that guards
the workspace until the exact staged supervisor takes ownership. Normal uv Python and dependency
resolution still needs network or pre-populated artifacts; failures retain the
bounded uv diagnostic.
Remote kernels run built-in plugins only. Project, user, and installed external
plugins are parsed as data but are not imported, executed, or staged for that
kernel. Creation emits one The following plugins have been ignored warning
with every ignored plugin and a redacted source. A single server can mix local
kernels with kernels on multiple SSH targets; listing, switching, recreation,
idle reaping, notebook attachment, PDB, images, and
cleanup retain each kernel's immutable location.
Windows, WSL path mapping, the ipi-windows/ipi-remote provisioners, and all
process-wide IPI_KERNEL_* settings have been removed. If a removed variable
is present, IPi exits with migration guidance to use an ssh:// cwd. See
Architecture for transport ownership and
Breaking Changes for migration details.
SSH troubleshooting and cleanup
Before launching, inspect the effective alias with ssh -G <alias> and prove
non-interactive authentication with ssh -o BatchMode=yes -T <alias> true.
Resolve an unknown host key or changed trust record through ordinary OpenSSH
administration first; IPi deliberately does not prompt, disable checking, or
edit known_hosts. A configured local agent may authenticate the client, but
IPi does not forward that agent to the target. Existing ProxyJump, port, and
identity settings remain OpenSSH's responsibility.
Resolving the latest portable uv requires host HTTPS access to GitHub. Later
Python and dependency resolution runs on the target and therefore needs its
normal uv cache or target network access. Both failures identify which side
needs access. A lost SSH connection may prevent immediate target verification;
the supervisor's owner lease then kills its kernel and removes its private
/tmp/ipi-session.* directory after roughly 60 seconds. Cleanup diagnostics
name the exact redacted SSH URI and owned paths. Audit only those exact paths
and processes; never delete a broad /tmp pattern. Passwords, Jupyter keys,
tokens, private-key paths, and signed query strings are not included in IPi
diagnostics.
Configuration And Plugins
IPi resolves the uv project or workspace member for each kernel cwd. Configuration merges ~/.ipi/config.toml, the workspace root's .ipi.toml, and the selected member's .ipi.toml, in that order. Outside a uv project, it uses <cwd>/.ipi.toml. Project plugins also come from the selected member. Each kernel retains its requested working directory. Missing config files are optional; invalid or inaccessible config fails.
Use ipinb --plugin DISTRIBUTION to add an already installed plugin for every local kernel location. Repeat it for more distributions. Existing per-location plugin selections and their version or source constraints remain in effect. This is useful for integrations owned by the server session when UV_PROJECT points outside its launch directory. Remote kernels continue to ignore external plugins with a warning.
[server]
kernel_idle_timeout_s = 0 # keep idle kernels alive; set a positive timeout to reap them
prewarm_kernel = true # start the default kernel in the background at startup
[tools]
inline_images = "all"
[kernel]
install_default_dependencies = true
additional_dependencies = []
scratch_dependencies = [] # personal packages only outside a uv project
locked = false # true requires an existing, current uv.lock
[plugins]
installed = []
disabled = []
Fresh kernels make a small general-purpose module set available: typing_extensions, attrs, packaging, platformdirs, pydantic, requests, dateutil, psutil, tqdm, filelock, more_itertools, yaml, tenacity, and dotenv. The last six come from bare, unversioned overlay requirements for tqdm, filelock, more-itertools, PyYAML, tenacity, and python-dotenv. Set kernel.install_default_dependencies = false to omit those six, or add PEP 508 requirements with kernel.additional_dependencies. A caller's explicit additional_dependencies value wins when it names the same distribution.
Put personal scientific and widget defaults in kernel.scratch_dependencies to keep them out of project kernels.
Local and SSH kernels use ephemeral uv run --isolated environments. uv selects the project, workspace membership, Python interpreter, sources, and normal default groups. IPi does not enable all extras or groups. Missing or stale locks are resolved temporarily without writing uv.lock, and IPi does not create or synchronize .venv. Set kernel.locked = true to require an existing current lock. Strict-lock mode checks the base project lock; kernel overrides can still select different package versions.
IPi requires uv 0.12.3 or later. Its runtime and additional dependencies use native uv overlays and may override project package pins. Each kernel has a private writable environment: live %pip changes affect only that kernel. Select the project with cwd and request extra packages with additional_dependencies; explicit venv attachment is not supported. Approved direnv settings apply to preparation and launch; IPi does not approve an .envrc.
The view_image tool is registered on every transport unless the startup configuration sets tools.view_image = false. Kernel-side guidance for written image files recommends view_image only when it is registered.
Plugins are ordinary Plugin(environment=..., kernel=...) values. They configure kernel environments and child IPython setup; they do not add MCP tools.
They can come from built-ins, selected ipi.extensions entry points,
~/.ipi/extensions/, or <cwd>/.ipi/extensions/. See
Developing External IPi Plugins for the API and
Architecture for ownership and lifecycle details.
Coding agents that create or debug plugins can opt into the
developing-ipi-plugins skill;
it is not auto-read by the MCP server.
Building Your Own Server
IPi is also a library. Runtime, register_tools and ToolOverride let you build an MCP server that starts kernels its own way, for example without a cwd argument, drops or renames standard tools, or changes their descriptions and annotations, while kernels, cells and transcripts behave exactly as in ipinb:
from pathlib import Path
from fastmcp import FastMCP
from ipi import Runtime, register_tools
runtime = Runtime(state_dir=Path("state"))
mcp = FastMCP("my-server", lifespan=runtime.lifespan)
register_tools(mcp, runtime, exclude={"create_kernel"})
See Building Your Own Server for a complete example.
Development
uv sync --all-extras --all-groups
uv run ruff check .
uv run ruff format --check .
uv run basedpyright
uv run pytest -m "not kernel and not live_api" -q
uv run pytest -m kernel -q
uv run python benchmarks/model_output_tokens.py
Breaking API changes are recorded in BREAKING_CHANGES.md. Release procedure is documented in docs/releasing.md.
Optional notebook startup in Codex
Configure the notebook MCP server as optional and set a positive mcp_optional_startup_grace_ms in Codex to let the first turn proceed while it starts. Zero disables the grace deadline and waits for startup. Newly ready tools appear at subsequent native catalog boundaries. Ordinary chat remains available if optional notebook startup fails.
Metadata
Release files for ipinb 0.7.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 |
|---|---|---|---|---|
| ipinb-0.7.0.tar.gz | 601.2 kB | With provenance | Details for ipinb-0.7.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| ipinb-0.7.0-py3-none-any.whl | Python 3 | none | any | Details for ipinb-0.7.0-py3-none-any.whl |
Total release size: 886.1 kB
Release files / ipinb-0.7.0.tar.gz
| Download URL | ipinb-0.7.0.tar.gz |
|---|---|
| Size | 601.2 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
f8027916b7e8d7d3d9116f69dd1f18230596b6ef3781ca2bd5e37a1b5dd980b6
|
|
BLAKE2b-256 checksum How to use checksums |
7f809648bf0897b4a81e1547d25de02c5ebea12b4acca835bbb8163415f7f759
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
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.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 8, 2026.
Transparency logRelease files / ipinb-0.7.0-py3-none-any.whl
| Download URL | ipinb-0.7.0-py3-none-any.whl |
|---|---|
| Size | 284.9 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
49a65ab816eb472dfdc608bc7dd1b10ddce17197f6010ff4e04d123d9f73531c
|
|
BLAKE2b-256 checksum How to use checksums |
f7a86227d077bd4989ed6d4b9fbc27030eda5ce8467888afbc1228673b6c9144
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
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.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 8, 2026.
Transparency logSecurity for ipinb 0.7.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.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for ipinb-0.7.0.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 8, 2026.
Transparency logA 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.