# sequential-reasoning-mcp

An MCP server that gives any MCP-compatible client (Claude Code, Claude
Desktop, Cursor, etc.) a way to hand off a sub-problem to a **fresh,
isolated context**, get back a distilled answer, and keep the verbose
intermediate reasoning out of the main conversation.

**No API key of any kind is required.** This server never calls a model
provider directly — it uses MCP's built-in **sampling** feature to ask the
*client you're already using* to run each completion, with its own message
list and `includeContext: "none"`, so the completion doesn't see your
conversation history. The host's existing model access (your Claude
subscription, your Cursor setup, whatever) is what actually runs the
model. This server holds no credentials and makes no outbound calls to any
LLM API.

Three tools:

| Tool | What it does |
|---|---|
| `plan` | Breaks a task into an ordered list of sequential steps. |
| `think_aside` | Reasons through **one** sub-question in a fresh, isolated sampling call (no chat history) and returns only the result. |
| `run_plan` | Runs `plan`, then works through each step **sequentially** via sampling, passing forward only a compressed summary between steps, then synthesizes a final answer. |

## Requirement: your MCP client must support sampling

This is the trade-off for not requiring a key: the server depends entirely
on the client implementing `sampling/createMessage`. Most agentic hosts do
(Claude Code and Claude Desktop do), but plain chat UIs or minimal clients
may not. If a tool call fails with something like "this MCP client may not
support the 'sampling' capability," that's what happened — there is no
API-key fallback path in this server by design.

## What this actually does (and doesn't)

A tool server cannot reach into its caller's context window and erase
anything — no MCP tool can, sampling included. What it *can* do is keep
verbose scratch reasoning from ever entering the main conversation, by
routing that reasoning through a separate sampling request with its own
explicit message list, and returning only the conclusion. That's the real
mechanism: **isolation of new reasoning via a fresh message list per call,
not deletion of old reasoning, and not a fresh account.**

`run_plan` is the sequential counterpart to parallel agentic tool-calling:
instead of firing off several tool calls at once and reconciling their
results, it works through steps one at a time, each step only seeing a
compressed summary of what came before — not the full transcript.

### On the `terse` reasoning style

`think_aside` and `run_plan` accept `style: "terse"`, which asks the model
to drop filler words while preserving all information. This is offered as
an **opt-in, unverified** trade-off, not a default:

- It has not been benchmarked against `normal` for accuracy on any specific
  task in this repo.
- Compressed/unnatural reasoning styles can plausibly hurt accuracy on
  tasks where the model benefits from thinking in fluent language, since
  models are trained to reason well in the style they're trained on.
- If you use `terse`, benchmark it on your own workload before relying on
  it for anything that matters. Don't assume it's a free win.

## Setup

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

That's it — no environment variables are required to run this server.

Optional environment override:

| Variable | Default | Purpose |
|---|---|---|
| `SRM_MAX_TOKENS` | `1024` | Max output tokens requested per sampling call |
| `SRM_MODEL_HINT` | unset | Optional model-name *hint* passed to the client's sampling request (`modelPreferences.hints`). The client decides what to actually run; this is advisory only, per the MCP spec. |

## Running it

```bash
node src/index.js
```

This starts an MCP server on stdio. Point any sampling-capable
MCP client at it.

## Client configuration

### Claude Code / Claude Desktop

Add to your MCP config (e.g. `~/.claude/settings.json` or the app's MCP
config file):

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

No `env` block needed — there's no key to pass.

### Claude.ai (web)

Claude.ai's web interface connects to **remote** MCP servers over HTTP/SSE,
not local stdio processes. To use this from claude.ai web, deploy it behind
an HTTP transport (see `@modelcontextprotocol/sdk`'s
`StreamableHTTPServerTransport` — a `src/http.js` variant is a natural next
addition to this repo) and add it as a custom connector under
Settings → Connectors. Sampling support over remote HTTP connectors depends
on the client-side implementation at the time you deploy this — verify
before relying on it. Until then, this server runs locally against
Claude Code, Cursor, or any other stdio-based, sampling-capable MCP client.

### Cursor

Add the same `command`/`args` block to Cursor's MCP settings
(`~/.cursor/mcp.json`). Confirm Cursor's current sampling support before
relying on this — client-side sampling support varies and changes over
time.

### Codex, Gemini, and other agents

Any client that speaks MCP over stdio *and* implements sampling can use the
same `command`/`args` pattern; consult that client's MCP configuration docs
for the exact file, and check whether it implements
`sampling/createMessage` before assuming this will work.

## Example: `run_plan`

```json
{
  "task": "Should I use a monolith or microservices for a 3-person startup's first product?"
}
```

Returns:

```json
{
  "steps": ["...", "...", "..."],
  "findings": [
    { "step": "...", "result": "..." },
    { "step": "...", "result": "..." }
  ],
  "final_answer": "..."
}
```

Each step's `result` is the *only* thing carried forward into the next
step's sampling request — not the full reasoning trace that produced it.

## Testing without a real model

`sampling/createMessage` can be stubbed with a fake client handler to
verify tool-call wiring without needing any live model — this is how the
plumbing in this repo was validated during development, since the server
itself never talks to a model provider directly. A `test/` suite built on
that pattern is on the roadmap.

## Roadmap

- [ ] HTTP/SSE transport for remote/claude.ai-web use
- [ ] Automated test suite using a stub sampling client (see above)
- [ ] Benchmark suite comparing `normal` vs `terse` style on accuracy and
      token count across a fixed task set
- [ ] Parallel-step mode for comparison against the sequential path

## License

MIT