# containerized-reasoning-mcp

MCP server that gives an LLM a disposable, step-by-step reasoning workflow, without calling
any model API itself. **No API key required.** The host model (whatever's driving the chat -
Claude, GPT, or anything else connected via MCP) does all the actual reasoning. This server
just tracks the plan and hands back only compressed summaries between steps, so the working
context stays small as the problem grows.

## How it differs from a "sub-agent" design

Some reasoning-pipeline MCP servers spin up their own internal LLM client (needing its own API
key) to do planning/reasoning/verification behind the scenes. This one doesn't call any model at
all - it's a pure state machine. The host model:

1. Breaks the problem into steps itself and calls `containerized_reasoning_mcp_start`.
2. Reasons through the returned step(s), using only the compressed prior summaries it's given
   (not full raw reasoning from earlier steps).
3. Calls `containerized_reasoning_mcp_submit_step` with a compressed summary, gets the next step(s) back.
4. Repeats until the plan is complete, then calls `containerized_reasoning_mcp_finalize`.

Because no model call happens inside the server, this works with **any** MCP-compatible client,
regardless of which model or provider is behind it - no `ANTHROPIC_API_KEY`, no provider lock-in.

### Trade-off vs. the sub-agent design

The upside is zero API key / zero extra cost / works everywhere. The trade-off: since the host
model does the reasoning in its own turns rather than in a truly separate hidden context, its
visible output for each step still appears in the conversation transcript (there's no hiding raw
reasoning traces the way a disposable sub-agent call could). What you still get is the discipline
of the pipeline (ordered/parallel steps, compressed handoff between them) and no dependency on a
second model or key.

## Pipeline

```
Problem -> (host plans steps) -> containerized_reasoning_mcp_start
   -> Step 1 (host reasons) -> containerized_reasoning_mcp_submit_step -> Step 2 ...
   -> ... -> plan complete -> containerized_reasoning_mcp_finalize -> Final Answer (+ optional verification)
```

Steps run in the order given. Steps sharing the same `parallelGroup` are handed back together as
independent work the host can do in either order.

## Setup

```bash
git clone https://github.com/devLlama/containerized-reasoning-mcp.git
cd containerized-reasoning-mcp
npm install
```

That's it - no environment variables, no API key.

## Run standalone

```bash
npm start
```

Runs as an MCP server over stdio.

## Install in an MCP client

Standard stdio MCP server - works with any client that supports MCP (Claude Desktop, Claude
Code, Cursor, Windsurf, claude.ai connectors, etc). Point the client at `node` plus the absolute
path to `src/index.js`. No `env` block needed.

### Claude Desktop

Edit your `claude_desktop_config.json` (Settings -> Developer -> Edit Config):

```json
{
  "mcpServers": {
    "containerized-reasoning": {
      "command": "node",
      "args": ["/absolute/path/to/containerized-reasoning-mcp/src/index.js"]
    }
  }
}
```

Restart Claude Desktop after saving.

### Claude Code

```bash
claude mcp add containerized-reasoning -- node /absolute/path/to/containerized-reasoning-mcp/src/index.js
```

Or add the same block as above to your project's `.mcp.json`.

### Cursor / Windsurf / any MCP-compatible app

Same `command`/`args` shape as above (Cursor's `mcp.json` uses the same schema). Consult that
app's docs for where its MCP config file lives.

### claude.ai web chat

claude.ai's web chat connects to **remote** (HTTP/SSE) MCP servers via Settings -> Connectors,
not local stdio processes launched from a browser tab. To use this server from claude.ai's web
chat specifically, you'd need to deploy it behind an HTTP/SSE MCP transport and register it as a
remote connector - running it locally via `node src/index.js` only works with clients that can
launch local stdio processes (Claude Desktop, Claude Code, Cursor, etc).

## Tools

| tool | purpose |
|------|---------|
| `containerized_reasoning_mcp_start` | Submit the problem + your own step plan; get the first step(s) back |
| `containerized_reasoning_mcp_submit_step` | Submit a step's compressed summary; get the next step(s) or a "plan complete" signal |
| `containerized_reasoning_mcp_finalize` | Submit the final answer (+ optional self-verification); get the compiled result, closes the session |
| `containerized_reasoning_mcp_get_state` | Inspect an in-progress session without submitting anything |
| `containerized_reasoning_mcp_discard` | Abandon a session |

Sessions are held in memory for the life of the server process (keyed by `sessionId`), so they
don't survive a server restart.