Imperal MCP

imperal-mcp - The Exoskeleton for Your AI Coding Agent 🐝

Stop babysitting your AI. Put it in an exoskeleton: it remembers everything, sees your whole codebase, can undo any change and can't fake a result - or hallucinate one past you. Fewer wasted tokens, fewer broken builds. Works with Claude Code, Cursor, OpenAI Codex, Gemini CLI, Windsurf, Claude Desktop, Cline and Goose.

pipx install "imperal-mcp[code]" && imperal-mcp login && imperal-mcp setup

Keep the quotes: zsh (the macOS default) reads [code] as a file pattern without them. No pipx yet? uv tool install "imperal-mcp[code]" does the same, or see Quick start.

The code tools work offline, no account needed. Memory across sessions, the kernel's frame and the hallucination check run on an Imperal Cloud account (imperal-mcp login) - sign-up is free, plans and credits: imperal.io/pricing.

The problem

AI coding agents are brilliant - and work blind:

• They forget. Every new session, every switch from Cursor to Claude Code, starts from zero. You explain your architecture again. And again.
• They burn tokens. To look at one function they read the whole 2,000-line file, then grep the repo and read three more files.
• They hallucinate. A function that doesn't exist. A file it never opened. "I updated the caller" - which one? "All tests pass" - nobody ran them. Said with total confidence, and you only find out in production.
• They break things. They edit a shared helper without knowing who calls it, and a failed experiment leaves your working tree dirty.

The fix: put your agent in an exoskeleton

imperal-mcp wraps the agent you already use. Same model, new abilities:

An illustration of one task - your own numbers: token_savings() measures them in every session.

WITHOUT the exoskeleton

1. cat service.py (1,800 lines) -> 72,000 chars dumped into context
2. grep -rn "process_order" . -> 140 noisy matches
3. read 3 more files to trace callers -> +95,000 chars burned
4. edit a shared function blind -> 2 callers broken, a syntax error left behind
5. "I also updated retry_backoff()" -> that function doesn't exist
6. "Done, tests pass!" -> it never ran them
7. open Cursor tomorrow -> total amnesia

WITH the exoskeleton

1. frame -> the task, what is proven, the code around your focus, the world
2. read_symbol("service.py", "Order.run") -> only the 28 lines that matter
3. impact_of_change(["Order.run"]) -> every caller, before you touch a line
4. checkpoint("before-refactor") -> undo in one call if it goes wrong
5. task(goal, items) -> an item closes only when the kernel saw the proof
6. "I also updated retry_backoff()" -> held back: no file it read holds that name
7. tomorrow, any tool -> recall: the whole history is there

Hallucinations: caught before they reach you

You can't trust a sentence just because it sounds sure. So the exoskeleton doesn't trust the model's words - it checks them against the record of what actually happened in this task.

On every step, the names the agent's thinking leans on - functions, files, sizes - are matched against what the task really read, what its commands really returned and what your code map really holds. A name found nowhere comes back in the next frame as NAMED BUT NOT FOUND, before the agent builds on it.

On the final answer, the same check runs once more. Name a symbol nobody read, a file nobody opened, a size nobody measured - and the answer doesn't reach you. It goes back to the agent:

KERNEL FACTS: your answer states what the kernel did not see happen:

• retry_backoff -- no file this task read and no output it got contains this name

Correct the answer to the facts, or do the missing work first.

The agent then reads the code it skipped, or corrects the claim. Either way, what you get is backed by something real.

On "done", words count for nothing: a plan item closes only on a proof the kernel measured - a diff, a check that exited 0, a finding with its sources. "Tests pass" without a test run is not a pass.

What it can't do - and we'd rather tell you: it doesn't make the model smarter. An agent can still draw a wrong conclusion from true facts. What it can no longer do is pass off what it never saw.

Powered by ICNLI - the new HTTP for AI

HTTP gave every computer one way to talk to every other. ICNLI gives people and AI agents - and agents among themselves - one way to work together that can be proven: whatever the model, whatever the tool.

[ICNLI](https://icnli.org) (Infrastructure Contextual Natural Language Interface) is the open protocol at the heart of the exoskeleton - and the reason it can promise honesty, not just speed.

Under ICNLI, an agent's work is a state the kernel can prove, not a story the model tells:

• Every step is measured. What a call read, changed or returned is recorded by the kernel - never taken from the model's words.
• Proven vs. claimed. The step frame shows what is proven and what is only claimed; a plan item is done only when its proof (a diff, a check that exited 0, a finding with sources) was seen.
• Decisions from facts. Progress, loops and stalls are computed from what the steps returned, and stated to the agent in plain words.
• One state, every surface. The same session state serves the terminal, the IDE, the web panel and Telegram.

MCP is how your agent talks to the exoskeleton. ICNLI is how the exoskeleton thinks. The specification is open (CC BY-SA 4.0) at icnli.org.

Quick start

# 1. Install (Python 3.7 - 3.14; the code map included) -- quotes required in zsh

pipx install "imperal-mcp[code]"

or: uv tool install "imperal-mcp[code]"

or: pip install "imperal-mcp[code]" only INSIDE a virtual environment: a bare pip install into the system

Python is refused on Debian 12+/Ubuntu 23.04+/Homebrew (error: externally-managed-environment)

no pipx? macOS: brew install pipx · Debian/Ubuntu: sudo apt install pipx · then: pipx ensurepath

2. Sign in to Imperal Cloud (memory, the kernel's frame, apps)

imperal-mcp login

3. Wire every shell found on this machine: server + hooks + protocol

imperal-mcp setup # Claude Code, Codex, Antigravity CLI, Gemini CLI

That's it. From the next prompt on, your agent starts each step from the kernel's frame, remembers across sessions and gets its final answer checked.

Other ways to connect

Claude Code only, in this project:

imperal-mcp claude-setup --with-hooks

Adds the imperal server to .mcp.json (keeps your entries, refuses to overwrite malformed JSON), appends the exoskeleton protocol to CLAUDE.md, and installs a PostToolUse hook that syntax-checks every Edit/Write.

Claude Code CLI:

claude mcp add imperal -- imperal-mcp

Cursor / Claude Desktop / Windsurf / Cline (.mcp.json or claude_desktop_config.json):

{

"mcpServers": { "imperal": { "command": "imperal-mcp", "args": [], "env": { "IMPERAL_WORKSPACE": "/absolute/path/to/your/repo" } } } }

Any other MCP stdio client: run imperal-mcp with IMPERAL_WORKSPACE set to your repository root.

Pricing: sign-up is free; plans and credits are on imperal.io/pricing. In imperal-mcp

only frame spends credits; every other tool is free, and the local code tools work offline.

For the geeks: how it works

The loop

1. `frame` - at the start and after each change. The kernel's step frame: the task and plan with what is proven, the code around the focus from the exact graph, what the change reaches, the machines and repos, the path so far, and a DECISION section to act on first. With imperal-mcp setup, the shell's prompt hook puts it in context automatically.
2. `task(goal, items)` - declare the request and the plan; an item closes only by a proof the kernel saw. An item that cannot be finished is marked blocked with the reason.
3. Code - orient -> outline -> read_symbol; search_code / grep_code for exact text; impact_of_change before editing a shared symbol. The same tools reach a server's repo with target="host: " or target="ssh: ".
4. Safety - checkpoint before risky edits, checkpoint_diff, checkpoint_rollback; check_syntax after.
5. Memory - every call, thought and answer is written to the vault by the shell's hooks; look back with recall, search_history, state_lens, vault_log_read.
6. The final check - the stop hook sends the final answer to the kernel: an answer that names a file, symbol or size the task never read is handed back to the agent, and open plan items are listed to you.

Hooks (installed by imperal-mcp setup)

Tool catalog (34 tools, 4 resources, 1 prompt)

Kernel & task (Imperal Cloud)

| state_lens(section?, focus?, conversation?) | What the kernel holds, by section (law, plan, reality, memory, conversation, path) - yours or another live sessio