Click on "Install Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@thought-graph-mcp should our team migrate from REST to GraphQL?"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
If it's hallucinating, make it think. Inspired by a research paper, this local MCP makes an LLM reason out loud as an explicit, editable graph of small thinking steps instead of one opaque answer.
Injects guidance that instructs the LLM to break a complex problem into
multiple smaller reasoning paths (returned by the begin_thinking tool).
Saves the thinking process to a Markdown file (.md) — every step, with
dependencies, branches, confidence, and revisions.
Renders an interactive HTML graph (.html) so you can see each step as a
node and how they connect.
Lets you understand how the LLM reached the answer by walking the graph node-by-node (click any node for its full reasoning).
Lets you pinpoint a specific step and regenerate it — the revise_step tool
supersedes that node, drops in a fresh revision, and tells the model which
downstream steps to reconsider.
https://github.com/user-attachments/assets/29162024-35ce-4b98-8be2-9745560fe16a
Explore a full web crawler system design session
https://github.com/user-attachments/assets/b3341f27-89af-460a-927f-b4f65a39090d
Related MCP server: Sequential Thinking MCP Server
Edit claude_desktop_config.json:
macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
{
"mcpServers": {
"thought-graph": {
"command": "npx",
"args": ["-y", "thought-graph-mcp"],
"env": {
"THOUGHT_GRAPH_DIR": "~/thought-graph-sessions"
}
}
}
}Session artifacts default to ~/thought-graph-sessions/. Override with THOUGHT_GRAPH_DIR in the server's env block if you want a different folder.
Restart Claude Desktop. Enable the server under the 🔌 (MCP) menu — the tools (begin_thinking, add_thought, etc.) become available to the model.
Project-scoped (create .mcp.json in your project root):
{
"mcpServers": {
"thought-graph": {
"command": "npx",
"args": ["-y", "thought-graph-mcp"]
}
}
}Or add it from the CLI:
claude mcp add thought-graph -- npx -y thought-graph-mcpVerify with claude mcp list.
In the client, ask:
Use the thought-graph tools to reason about: should our team migrate from REST to GraphQL?
The model will call begin_thinking, decompose into sub-problems, branch competing
hypotheses, attach evidence, and finalize_thinking. Open the generated .html:
Click a node → full reasoning + its dependencies in the side panel.
Spot a weak step (e.g. n4) → tell the assistant
"revise step n4 of session — that assumption is wrong because …".
It calls revise_step, the node is dimmed as superseded, a revision replaces it,
and the graph rebuilds.
Here are a few examples of using the MCP tool to analyze mission-critical LLM inference.
Example | Problem | Nodes | Directory |
Web crawler system design + BOTE | Design a crawler for ~1B pages/month — politeness, dedup, refresh — with back-of-the-envelope sizing for storage, bandwidth, QPS, and fleet size | 18 | |
Rate limit service design | Design a distributed rate limiter — high throughput, low latency, flexible per-user/key/endpoint rules, graceful degradation | 21 | |
Autocomplete feature design | Design typeahead suggestions — data source, matching/ranking, frontend UX, latency, accessibility | 14 |
The guidance in src/prompt.ts is injected into the context window when the tool begin_thinking is called, instructing the model to build the thought graph.
Every node in the graph has a type. It drives node color in the HTML graph, grouping in the Markdown export, and the shape of the reasoning protocol the model follows.
Type | Label | What it represents | How it's created |
| 🎯 Problem | The original question the session is about | Automatically by |
| 🔱 Decompose | A framing step that breaks the problem into axes or sub-questions |
|
| 🧩 Sub-problem | One focused piece of the larger problem to solve |
|
| 💡 Hypothesis | A candidate idea or approach — sibling hypotheses are parallel branches |
|
| 📎 Evidence | A fact, observation, or computation that supports a path |
|
| ⚖️ Evaluation | Weighing trade-offs or checking whether a hypothesis holds |
|
| ♻️ Revision | A corrected replacement for an earlier step | Automatically by |
| ✅ Conclusion | A synthesized partial or final answer for a branch |
|
Typical flow: root → decompose → one or more subproblem nodes → competing hypothesis branches on each → evidence / evaluation attached to the relevant branch → conclusion nodes that merge paths → finalize_thinking for the overall answer. If a step turns out wrong, revise_step inserts a revision node and flags downstream dependents for reconsideration.
npx -y thought-graph-mcp downloads the npm package and its dependencies into your npm/npx cache, then runs the MCP server as a Node.js process over stdio. You do not need to clone this repo or run a bundler.
What | Approx. size | Role |
npm package ( | ~280 KB download · ~1.2 MB unpacked | Compiled MCP server ( |
npm dependencies (installed once, cached by npx) | ~45–55 MB on disk | Libraries the server uses at runtime (see table below) |
Session folder (grows as you reason) | ~0.7–1 MB per session | Self-contained graph file (embeds static CSS/JS from the package) plus ~10–20 KB |
Total first-time footprint: roughly 50–60 MB in npm cache. Each session .html is ~0.7–1 MB (mostly the graph runtime block below).
npx installs (gzip treemap)Treemap region | bundled | share | What it is |
| 209.4 KB | 71% | Graph HTML stack: cytoscape, html2canvas, dagre, marked, dompurify, |
| 86.4 KB | 29% | MCP server process: |
Total | 295.8 KB | 100% | Minified production dependency tree (gzip); on disk |
After your first begin_thinking call, expect this layout:
~/thought-graph-sessions/
assets/ # static graph runtime (copied once per package version)
.asset-version
vendor/ # cytoscape, dagre, marked, html2canvas, … (~1 MB)
graph/ # graph.css, graph.client.js (~22 KB)
sessions/
my-problem-abc12345.html ~0.7–1 MB — embeds assets (Claude in-app browser)
my-problem-abc12345.json ~10–20 KB
my-problem-abc12345.md ~10 KBRecord one reasoning step (a graph node). Keep it to a single idea. Use parents to link it to the node(s) it builds on — list several to merge branches. Create sibling nodes with the same parent to explore competing paths.
| Name | Required | Description | Default |
|---|---|---|---|
| type | Yes | One of: decompose, subproblem, hypothesis, evidence, evaluation, conclusion (use revise_step for revisions). | |
| title | Yes | Short label for the node (shown on the graph). | |
| branch | No | Optional branch label, e.g. "approach A". | |
| content | Yes | The full reasoning text for this step. | |
| parents | No | Ids of nodes this builds on, e.g. ["n1","n3"]. | |
| sessionId | Yes | ||
| confidence | No | Optional self-rated confidence 0..1. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It discloses that adding a thought creates a graph node and links with parents, but does not mention side effects, persistence, permissions, or limits. The description is adequate but not deeply transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise with three sentences. It front-loads the main action and immediately provides key guidance. Every sentence adds value without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool complexity (7 params, 4 required, enum, array) and lack of output schema, the description covers the core functionality well. It misses some behavioral details (e.g., return value), but overall is fairly complete for agent usage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is high (86%), so baseline is 3. The description adds value by explaining how 'parents' are used for linking and merging, and reinforces the 'type' constraint. It does not duplicate schema information unnecessarily.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's action ('Record') and resource ('one reasoning step (a graph node)'). It differentiates from sibling tools by focusing on adding nodes vs. revising or finalizing. It also specifies constraints like 'keep it to a single idea'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit guidance on usage, such as using 'parents' to link nodes, merging branches, and creating sibling nodes. It implies when to use (to add a reasoning step) but lacks explicit exclusions or direct comparisons to siblings like 'revise_step' (though noted in schema).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Start a new Thought Graph reasoning session for a complex problem. Returns a sessionId and the protocol instructions. Call this FIRST, then build the reasoning with add_thought.
| Name | Required | Description | Default |
|---|---|---|---|
| title | No | Short title for the session (defaults to the problem). | |
| problem | Yes | The complex problem/question to reason about. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It discloses that the tool returns a sessionId and protocol instructions and initiates a new session. However, it does not mention potential side effects, idempotency, or any constraints (e.g., session limits). The disclosure is adequate but not exhaustive for a creation tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise, consisting of only two sentences. The first sentence states the purpose, and the second provides crucial sequential guidance. No redundant or extraneous information is present, making it highly efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with only two parameters and no output schema, the description is sufficiently complete. It explains the tool's role as the entry point and mentions return values. While it doesn't elaborate on the protocol instructions, this is acceptable given the likely complexity of a reasoning session starter. The description covers the essential information.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema covers both parameters with descriptions, achieving 100% coverage. The description does not add information beyond what the schema provides (the default behavior for title is already in the schema). Therefore, the description adds no extra value to parameter semantics, resulting in a baseline score of 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies the tool's action: starting a new Thought Graph reasoning session. It specifies the verb 'Start' and the resource 'Thought Graph reasoning session', and distinguishes itself from siblings by stating 'Call this FIRST, then build the reasoning with add_thought.' This provides a specific, unambiguous purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives explicit sequential guidance: 'Call this FIRST, then build the reasoning with add_thought.' This indicates when to use the tool relative to its siblings. However, it does not explicitly state when not to use it or mention alternatives beyond the sequential hint, which is a minor gap for a perfect score.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Record the final synthesized answer for the session and refresh the artifacts. Call after the graph supports a conclusion.
| Name | Required | Description | Default |
|---|---|---|---|
| answer | Yes | ||
| sessionId | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must fully disclose behavior. It mentions recording an answer and refreshing artifacts, but does not explain side effects, overwriting behavior, or what 'refresh the artifacts' entails. This leaves some gaps for an agent reasoning about state changes.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise with just two sentences. Every phrase adds value: the action, the scope (session), the secondary effect (refresh artifacts), and the usage context. No unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the primary action and usage context, but lacks details on return values, confirmation, or error conditions. Given no output schema and no annotations, the agent may need more information to handle edge cases or verify success.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description adds no semantic detail for 'sessionId' or 'answer'. While the parameter names are somewhat self-explanatory, the description should clarify the expected format or constraints for 'answer', especially given no enums or additional schema guidance.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool records the final synthesized answer and refreshes artifacts, using specific verbs and resources. It distinguishes 'finalize' from sibling tools like 'add_thought' and 'revise_step' by framing it as the final action after a conclusion is reached.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives specific timing guidance: 'Call after the graph supports a conclusion.' While it doesn't explicitly list when not to use it, this instruction clearly differentiates it from more intermediate siblings like 'add_thought' or 'begin_thinking'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Return the current reasoning graph as JSON (all nodes, edges, statuses) plus on-disk artifact paths. Use this to review where things stand or recover the exact graph file path.
| Name | Required | Description | Default |
|---|---|---|---|
| sessionId | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description must fully disclose behavior. It states the tool returns JSON and artifact paths, implying a read-only operation. However, it does not mention permissions, error handling, or side effects, which would be beneficial.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences: first defines the tool's output, second gives usage guidance. Every word adds value, with no repetition or fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple retrieval tool with one required parameter and no output schema, the description covers the key outputs (graph JSON with nodes/edges/statuses, artifact paths) and suggests use cases. Could be slightly improved by noting what happens if sessionId is invalid.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The single parameter 'sessionId' is a string with no description in the schema (0% coverage). The tool description adds no explanation about what sessionId represents (e.g., 'the ID of the session to retrieve'), leaving the agent to infer from context.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Return' and the resource 'current reasoning graph as JSON' along with on-disk artifact paths. It distinguishes from sibling tools like list_sessions (which lists sessions) and add_thought (which modifies graph).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly advises using this tool 'to review where things stand or recover the exact graph file path,' providing clear context. It does not explicitly state when not to use it or mention alternatives, but the siblings list helps differentiate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List existing Thought Graph sessions (id, title, step count) found on disk.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description only states it lists sessions from disk. It does not clarify that this is a read-only operation, nor does it mention any potential side effects, performance implications, or handling of empty results.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single, well-structured sentence that immediately conveys the tool's purpose. No unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple list tool with no parameters and no output schema, the description is minimal but adequate. It could be improved by clarifying behavior when no sessions exist or if results are ordered.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
No parameters exist, so baseline is 4. The description adds context about what the tool lists (sessions with id, title, step count) beyond the empty schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists existing Thought Graph sessions with specific fields (id, title, step count) from disk. It distinguishes from siblings like get_session (single session) and add_thought (add).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives. For example, it does not mention that get_session is for retrieving a single session or that sibling tools are for other operations.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Pinpoint a specific step by node id, mark it superseded, and replace it with a fresh revision node. Returns the downstream nodes you should re-examine. Use when the user points at a step or you find a flaw.
| Name | Required | Description | Default |
|---|---|---|---|
| nodeId | Yes | The node to revise, e.g. "n4". | |
| newTitle | No | Optional new label. | |
| sessionId | Yes | ||
| newContent | Yes | The regenerated reasoning for this step. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description must disclose behavior. It states the tool supersedes and replaces a node and returns downstream nodes, but omits prerequisites, error conditions, or authorization needs. Some behavioral info present but incomplete.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, no filler. Action and output are front-loaded. Every word is meaningful.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema and no annotations, the description covers main action and output but lacks detail on error scenarios, prerequisites, or the exact nature of 'downstream nodes'. Adequate but with notable gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 75% (3 of 4 parameters have descriptions). The description adds marginal value by restating nodeId purpose and relating newContent to replacement, but does not enhance parameter understanding beyond the schema. Baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the tool pinpoints a step by node ID, marks it superseded, and replaces it with a fresh revision node. It also mentions returning downstream nodes for re-examination. This distinguishes it from sibling tools like add_thought.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit guidance: 'Use when the user points at a step or you find a flaw.' Does not mention when not to use or alternatives, but context with siblings is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.
v0.1.0add_thoughtbegin_thinkingfinalize_thinkingget_sessionlist_sessionsrevise_stepEach tool has a clear, distinct purpose: starting a session, adding steps, revising, finalizing, and retrieving sessions. No overlap or ambiguity.
All tools use underscore_case with a verb_noun or verb_gerund pattern (e.g., add_thought, begin_thinking, list_sessions), maintaining consistency throughout.
6 tools is well-scoped for a reasoning graph system, covering core operations without unnecessary bloat.
Covers the essential lifecycle: start, add, revise, finalize, and retrieve. Missing explicit deletion of sessions or thoughts, but these are minor gaps.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
Turn AI conversations into visual knowledge maps. Create, connect, search, and organize thoughts.
Turn grounded AI answers into trusted comparisons, plans, timelines, and decision views.
Evidence-grounded, graph-connected, correctable memory for agents.
Deterministic reasoning stack for AI agents: simulate, decide & compute, plus cross-domain tools.
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/jeff-ong/thought-graph-mcp'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
