mcp-sequentialthinking-tools
A lightweight MCP server for recording sequential reasoning steps. It
is a scratchpad with history, branching, revision metadata, and
optional validation for model-authored tool plans.
It does not discover your other MCP tools and it does not
choose tools for the model. If you pass available_tools and
recommended_tools, the server validates that the recommended names
exist and stores the step.
Why use it?
Use this when a task benefits from explicit, inspectable reasoning:
- breaking a messy problem into steps;
- revising or branching a plan;
- keeping a small reasoning history by session;
- validating tool-plan names against a supplied tool list;
- clearing or inspecting reasoning history during a long agent run.
Do not use it for trivial requests. It adds overhead.
Tools
sequentialthinking_tools
Records one thought.
Required parameters:
thought— current reasoning stepthought_number— current step numbertotal_thoughts— current estimate; automatically raised if lower
thanthought_numbernext_thought_needed— whether another thought is needed
Optional parameters:
session_id— history bucket; defaults todefaultis_revision,revises_thoughtbranch_from_thought,branch_idneeds_more_thoughtsavailable_tools— array of tool names or{ name, description }
objectsrecommended_tools— model-authored recommendations to
validate/storeremaining_steps— short list of upcoming steps
Example:```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
}
]
}
If `recommended_tools` contains a name not present in
`available_tools`, the call returns `isError: true` and does not store
the thought.
## Security posture
The server treats thought text, tool descriptions, rationales, and
remaining-step text as untrusted input. Prompt-injection-like text is
scanned and redacted before it is stored or returned in history. Calls
with redactions include `security_warnings` showing which fields
matched.
This is defensive filtering, not a guarantee that arbitrary
adversarial text is safe. Do not put secrets in thoughts or tool
descriptions.
### `get_thinking_history`
Returns stored thoughts for a session.
Parameters:
- `session_id` — defaults to `default`
- `branch_id` — optional branch filter
- `limit` — max records to return; default `50`, max `500`
### `clear_thinking_history`
Clears one session or every session.
Parameters:
- `session_id` — defaults to `default`
- `all_sessions` — clear all history buckets
## Prompt
### `sequential-thinking-guidance`
A short prompt that tells the model how to use this server honestly:
as a scratchpad and validator, not as an external reasoning engine.
## Configuration
### Claude Desktop / compatible MCP clients```json
{
"mcpServers": {
"mcp-sequentialthinking-tools": {
"command": "npx",
"args": ["-y", "mcp-sequentialthinking-tools"],
"env": {
"MAX_HISTORY_SIZE": "1000"
}
}
}
}
MAX_HISTORY_SIZE is per session and defaults to 1000.
The server uses tmcp and includes a small stdio transport that
accepts both standard Content-Length framed MCP messages and
newline-delimited JSON used by older tmcp tooling.
Development```bash
pnpm install
pnpm test
pnpm build
pnpm check
This project uses `vite-plus` for build, test, format, and lint
orchestration.
## Publishing```bash
pnpm changeset
pnpm changeset version
pnpm release
License
MIT License — see LICENSE.
Acknowledgments
- Built on the
Model Context Protocol - Adapted from the
MCP Sequential Thinking Server
