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

Option A: from npm (recommended once published)

npm install -g containerized-reasoning-mcp

Option B: from source

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

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):

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

Restart Claude Desktop after saving.

Claude Code

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).

Cursor

Add to .cursor/mcp.json (project) or ~/.cursor/mcp.json (global):

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

If published to npm, you can use "command": "npx", "args": ["-y", "containerized-reasoning-mcp"] instead. Restart Cursor and check Settings -> Tools & MCP for a green status dot.

OpenAI Codex (CLI / IDE extension / desktop app)

Codex supports local stdio MCP servers directly - no separate app review needed for CLI/IDE/desktop use:

codex mcp add containerized-reasoning -- node /absolute/path/to/containerized-reasoning-mcp/src/index.js

or add the same command/args block to ~/.codex/config.toml under mcp_servers. Run /mcp inside a Codex session to confirm it's connected. (This is separate from ChatGPT's hosted "Apps" marketplace, which currently only accepts remote Streamable HTTP MCP servers - see below.)

Gemini CLI

Create a gemini-extension.json:

{
  "name": "containerized-reasoning-mcp",
  "version": "0.2.0",
  "mcpServers": {
    "containerized-reasoning": {
      "command": "node",
      "args": ["src/index.js"]
    }
  }
}

Users can then install it with gemini extensions install <your-repo-url>, or you can list it in the Gemini CLI extensions gallery once published.

ChatGPT (hosted Apps / Apps SDK)

ChatGPT's in-chat App marketplace only accepts remote Streamable HTTP MCP servers with OAuth and a domain-ownership verification step (/.well-known/openai-apps-challenge) - it does not run local stdio processes the way Claude Desktop, Cursor, Codex, or Gemini CLI do. To make this server usable inside hosted ChatGPT, you'd need to wrap it behind a remote HTTP MCP transport and go through OpenAI's Apps SDK submission process. As-is, this repo works as a local stdio server with any MCP client that supports that transport.

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.

Privacy

This server makes no network calls and stores no data outside the running process's memory. Session state (problem text, step plan, step summaries) lives only in RAM for the life of the process and is discarded on restart or when a session is finalized/discarded. Nothing is written to disk, sent to a third party, or persisted anywhere by this server itself. (Whatever MCP client and host model you connect it to may have their own logging/telemetry - that's outside this server's control.)

Contributing

Bug reports, feature requests, and pull requests are welcome - see CONTRIBUTING.md.

License

MIT - see LICENSE. Free to use, modify, and redistribute, including commercially, as long as the copyright notice is kept.