# spences10/mcp-sequentialthinking-tools: a reasoning scratchpad that validates tool plans

> This MCP server stores sequential reasoning steps per session, with branching, revision metadata and optional validation of model-authored tool recommendations. It is not a tool router, and the README is explicit about that.

**spences10/mcp-sequentialthinking-tools** — 🧠 An adaptation of the MCP Sequential Thinking Server to guide tool usage. This server provides recommendations for which MCP tools would be most effective at each stage.

- Repository: https://github.com/spences10/mcp-sequentialthinking-tools
- Stars: 590 · Forks: 85
- Language: TypeScript
- License: MIT
- Published: 2026-09-10 · Updated: 2026-09-10 · Language: en
- Canonical page: https://hysenlabs.com/projects/spences10-mcp-sequentialthinking-tools

## What sequentialthinking_tools actually does, and what it refuses to do

The name invites a wrong assumption. The README opens with a correction: this server "does not discover your other MCP tools and it does not choose tools for the model." It is a scratchpad with history. You hand it a thought, a step number, an estimate of total steps and a flag for whether another thought is needed, and it stores that step in a session bucket. The tool-planning angle is narrower than the title suggests. If you pass available_tools and recommended_tools, the server checks that every recommended name exists in the supplied list, then stores the step. That is a name check against a list you provide, not a ranking and not a decision. The audience is narrow too: agent authors who want the reasoning trace to be a first-class, queryable artifact rather than text buried in a transcript. If your task is a one-shot question, the README says plainly not to use it for trivial requests, because it adds overhead.

## How a thought is stored, branched and revised

Four parameters are required on every call: thought, thought_number, total_thoughts and next_thought_needed. The README notes that total_thoughts is raised automatically when it is lower than thought_number, so an early underestimate does not break the sequence. Sessions are the storage unit. session_id defaults to the string "default", which means a client that never sets it writes everything into one bucket. Branching uses branch_from_thought and branch_id, and revision uses is_revision with revises_thought, so a plan can fork and a step can be superseded without deleting the original record. The server treats thought text, tool descriptions, rationales and remaining-step text as untrusted input. Prompt-injection-like text is scanned and redacted before storage or before it is returned in history, and calls that trigger redaction carry security_warnings naming the matched fields. The README frames this as defensive filtering rather than a guarantee, and warns against putting secrets in thoughts or tool descriptions. That warning is worth taking literally: the redaction targets injection-shaped text, not credentials.

## Installing it and recording a first validated thought

The package ships a bin entry, so the README configures it through npx rather than a global install. The Node engine is set to >=22.0.0 in package.json, so an older runtime will fail before the server starts. The configuration block below is the one the README gives for Claude Desktop and compatible MCP clients, including the MAX_HISTORY_SIZE environment variable, which is per session and defaults to 1000.

```json
{
	"mcpServers": {
		"mcp-sequentialthinking-tools": {
			"command": "npx",
			"args": ["-y", "mcp-sequentialthinking-tools"],
			"env": {
				"MAX_HISTORY_SIZE": "1000"
			}
		}
	}
}
```

Once the client starts the server, the first real call is a single thought with a tool recommendation attached. The README gives this example, and the recommended_tools entry names read, which must also appear in available_tools or the call fails.

```json
{
	"session_id": "svelte-debug",
	"thought": "First inspect the route files, then run the failing check.",
	"thought_number": 1,
	"total_thoughts": 3,
	"next_thought_needed": true,
	"available_tools": ["read", "bash"],
	"recommended_tools": [
		{
			"tool_name": "read",
			"confidence": 0.9,
			"rationale": "Need to inspect the relevant files before editing.",
			"priority": 1
		}
	]
}
```

To read the step back, call get_thinking_history with the same session_id; the README documents a limit parameter with a default of 50 and a maximum of 500. To start over, clear_thinking_history takes a session_id or all_sessions. If you are building from source rather than running the published package, the README lists the development commands:

```bash
pnpm install
pnpm test
pnpm build
pnpm check
```

## The validation failure mode you will hit first

The most likely first error is a name mismatch. If recommended_tools contains a name that is not present in available_tools, the call returns isError: true and the thought is not stored. Nothing is partially written. That is a clean failure, but it has a consequence worth planning for: a model that invents a plausible tool name loses the whole step, including the reasoning text that was fine. Your agent loop needs to handle that response and retry with a corrected name, or the reasoning history will silently have holes exactly where the model was most confused. The available_tools parameter accepts either an array of tool names or objects with name and description. Passing bare names is cheaper, but it gives the validator nothing to match against beyond the string, and the README does not describe any fuzzy or partial matching.

## Where the scratchpad model breaks down

History is capped. MAX_HISTORY_SIZE is per session and defaults to 1000, and get_thinking_history has its own limit parameter with a default of 50 and a maximum of 500. A long agent run that writes thousands of steps will not return everything in one query, and the README does not document rollback or an export path for the evicted records. There is no documented persistence layer either. The README describes storage per session and a clear operation, but says nothing about where the data lives between client restarts, so treat the history as run-scoped until you confirm otherwise. The security filtering is the other soft edge. It redacts injection-like text, and the README itself says this is not a guarantee that arbitrary adversarial text is safe. If your threat model requires provable isolation of untrusted tool descriptions, this server is not that boundary.

## Sequential thinking MCP alternative: the upstream server without validation

The README credits the MCP Sequential Thinking Server as the source this project was adapted from. The difference is the tool-planning layer. Upstream records thoughts; this fork adds available_tools, recommended_tools and the name check that returns isError when a recommendation does not exist in the supplied list, plus the redaction pass over stored text with security_warnings in the response. If you only want step-by-step reasoning recorded and you have no interest in validating tool names, the upstream server is the smaller dependency. If you want the validation, you are choosing a project that is at v0.1.0 with a single release so far, so weigh that against a more established base. The transport is also a deliberate compatibility choice: the README states the server includes a small stdio transport that accepts both standard Content-Length framed MCP messages and newline-delimited JSON used by older tmcp tooling.

## Maintenance, licence and the cost of staying current

The repository is not archived. Its last push was on 2026-09-10, and the only release listed is v0.1.0 from 2026-08-25, so the project is early rather than settled. The dependency set is small and mostly pinned to the tmcp family: tmcp, @tmcp/adapter-valibot and @tmcp/transport-stdio, with valibot for schema validation. That is a thin surface, which keeps upgrade work modest, but it also means the server's behaviour is tied to tmcp's transport conventions. Development uses pnpm with vite-plus orchestrating build, test, format and lint, and releases go through changesets. A renovate.json at the top level suggests dependency updates are automated. The licence is MIT, which permits commercial use and modification provided the copyright notice and permission notice are retained; this is a description of the licence text, not legal advice, and you should read LICENSE yourself before redistributing.

## Conclusion

Adopt it if you want an inspectable per-session reasoning log and you already control which tools exist, because the validation only checks recommended names against the available_tools list you pass in. Skip it for trivial requests, since the README says it adds overhead, and skip it if you expected a server that discovers tools or picks one for the model. Before wiring it into a client, verify two things: that your Node runtime is 22 or newer, because package.json sets engines to >=22.0.0, and that your client can speak the stdio transport, which accepts both Content-Length framed messages and newline-delimited JSON. Then open a session, send an intentionally wrong recommended_tools name, and confirm the call comes back with isError: true and nothing stored.

## FAQ

### What does sequential thinking (MCP) do in mcp-sequentialthinking-tools?

It records one reasoning step per call, storing the thought text, step number, total estimate and whether another thought is needed in a session bucket. Optional branching, revision metadata and validation of recommended tool names are stored alongside the step.

### What are some examples of MCP tools in this server?

The server exposes three tools: sequentialthinking_tools for recording a thought, get_thinking_history for reading stored thoughts for a session, and clear_thinking_history for clearing one session or every session. It also ships a prompt named sequential-thinking-guidance.

### How many tools should a mcp-sequentialthinking-tools server have?

The README does not discuss a recommended tool count for MCP servers. This project itself exposes three tools plus one prompt, and the README gives no guidance on sizing a server beyond that.

## Sources

- [Issues](https://github.com/spences10/mcp-sequentialthinking-tools/issues)
- [License: MIT](https://github.com/spences10/mcp-sequentialthinking-tools/blob/main/LICENSE)
- [README](https://github.com/spences10/mcp-sequentialthinking-tools/blob/main/README.md)
- [Releases](https://github.com/spences10/mcp-sequentialthinking-tools/releases)
- [spences10/mcp-sequentialthinking-tools on GitHub](https://github.com/spences10/mcp-sequentialthinking-tools)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/spences10-mcp-sequentialthinking-tools