Power your agent
The publisher's own command. Not a PlugMCP endpoint.
Host a copy with our keys and logs.
npx -y @kastalien-research/[email protected]Claude Code has no install link for a local command. Copy the command below and run it in a terminal.
claude mcp add io.github.kastalien-research-thoughtbox -- npx -y @kastalien-research/thoughtbox@1.0.3Run in a terminal.
{ "mcpServers": { "io.github.kastalien-research-thoughtbox": { "command": "npx", "args": [ "-y", "@kastalien-research/[email protected]" ] } }}claude_desktop_config.json
Remote URL or a command on your machine? How the two installs differ
Run on PlugMCP
A new server you create. It is not this listing's official endpoint. Use the publisher install when you want their URL and their credentials.
LaunchFrom the publisher
Multi-agent collaborative reasoning that's auditable. Thoughtbox is an MCP server for structured, multi-agent reasoning, with a companion web app for workspace and inspection flows. Every step is recorded as a structured thought in a persistent reasoning ledger that can be visualized, exported, and analyzed.
Runtime modes: Local development can use filesystem or in-memory storage. Deployed mode uses Supabase-backed storage, and the current production MCP server runs on Cloud Run.
Extended reasoning with structured processes, persistence, and workflow guidance
Observatory UI showing a reasoning session with 14 thoughts and a branch exploration (purple nodes 13-14) forking from thought 5.
Thoughtbox exposes exactly two MCP tools using the Code Mode pattern:
thoughtbox_search — Write JavaScript to query the operation/prompt/resource catalog. The LLM has full programmatic filtering power over the catalog.thoughtbox_execute — Write JavaScript using the tb SDK to chain operations. Access thoughts, sessions, knowledge, notebooks, hub, observability, and protocol tools through a unified namespace.Workflow: search to discover available operations, then execute code against them. Use console.log() for debugging — output is captured in response logs.
This replaces per-operation tool registration with a two-tool surface that scales without context window bloat.
The Hub is the coordination layer. Agents register with role-specific profiles, join shared workspaces, and work through a structured problem-solving workflow — all via thoughtbox_execute.
The workflow: register → create workspace → create problem → claim → work → propose solution → peer review → merge → consensus
Workspace primitives:
Agent Profiles: MANAGER, ARCHITECT, DEBUGGER, SECURITY, RESEARCHER, REVIEWER — each provides domain-specific mental models and behavioral priming.
28 operations across identity, workspace management, problems, proposals, consensus, channels, and status reporting.
Every thought is a node in a graph — numbered, timestamped, linked to its predecessors, and persisted across sessions. This creates an auditable trail of how conclusions were reached.
Agents can think forward, plan backward, branch into parallel explorations, and revise earlier conclusions. Each pattern is a first-class operation:
Each thought carries a semantic thoughtType (reasoning, decision_frame, action_report, belief_snapshot, assumption_update, context_snapshot, progress) that classifies what kind of thought it is, orthogonal to the process pattern used.
See the Patterns Cookbook for comprehensive examples.
The Observatory is a built-in web UI at http://localhost:1729 for watching reasoning unfold live.
The full observability stack includes OpenTelemetry tracing, Prometheus metrics, and Grafana dashboards.
Knowledge Graph — Persistent memory across sessions. Capture insights, concepts, workflows, and decisions as typed entities with typed relations (BUILDS_ON, CONTRADICTS, SUPERSEDES, etc.) and visibility controls (public, agent-private, team-private).
Notebooks — Interactive literate programming combining documentation with executable JavaScript/TypeScript in isolated environments.
Thoughtbox is currently optimized for Claude Code. We are actively working on supporting additional MCP clients. Due to variation in capability support across the MCP ecosystem — server features (prompts, resources, tools), client features (roots, sampling, elicitation), and behaviors like
listChangednotifications — we implement custom adaptations for many clients.
If you're using a client other than Claude Code and encounter issues, please open an issue describing your client and the problem.
Thoughtbox runs as a Docker-based MCP server. It requires Docker and Docker Compose.
git clone https://github.com/Kastalien-Research/thoughtbox.git
cd thoughtbox
docker compose up --build
This starts Thoughtbox and the full observability stack. The MCP server listens on port 1731 and the Observatory UI is available at http://localhost:1729.
Since Thoughtbox uses HTTP transport, configure your MCP client to connect via URL.
Add to your ~/.claude/settings.json or project .claude/settings.json:
{
"mcpServers": {
"thoughtbox": {
"url": "http://localhost:1731/mcp"
}
}
}
To connect through the observability sidecar (adds OpenTelemetry tracing):
{
"mcpServers": {
"thoughtbox": {
"url": "http://localhost:4000/mcp"
}
}
}
Add to your MCP settings or .vscode/mcp.json:
{
"servers": {
"thoughtbox": {
"url": "http://localhost:1731/mcp"
}
}
}
Thought 1: "Users report slow checkout. Let's analyze..."
Thought 2: "Data shows 45s average, target is 10s..."
Thought 3: "Root causes: 3 API calls, no caching..."
Thought 4: "Options: Redis cache, query optimization, parallel calls..."
Thought 5: "Recommendation: Implement Redis cache for product data"
Thought 8: [GOAL] "System handles 10k req/s with <100ms latency"
Thought 7: "Before that: monitoring and alerting operational"
Thought 6: "Before that: resilience patterns implemented"
Thought 5: "Before that: caching layer with invalidation"
...
Thought 1: [START] "Current state: 1k req/s, 500ms latency"
Thought 4: "Need to choose database architecture..."
Branch A (thought 5): branchId="sql-path"
"PostgreSQL: ACID compliance, mature tooling, relational integrity"
Branch B (thought 5): branchId="nosql-path"
"MongoDB: Flexible schema, horizontal scaling, document model"
Thought 6: [SYNTHESIS] "Use PostgreSQL for transactions, MongoDB for analytics"
For local development (requires Node.js 22+):
pnpm install
pnpm build
pnpm dev # Development with hot reload
npx vitest run # Unit tests
pnpm test # Full suite (build + vitest)
pnpm test:agentic # Agentic tests — full suite (build + run)
pnpm test:agentic:tool # Agentic tests — tool-level only
pnpm test:agentic:quick # Agentic tests — quick (no build)
pnpm test:behavioral # Behavioral contract tests
docker compose up --build starts the full stack:
Persistent data is stored in named volumes: thoughtbox-data, prometheus-data, grafana-data.
src/
├── index.ts # Entry point (Streamable HTTP transport)
├── server-factory.ts # MCP server factory with tool registration
├── thought-handler.ts # Core thought recording logic
├── types.ts # Shared type definitions
├── database.types.ts # Supabase generated types
├── code-mode/ # Code Mode tool surface
│ ├── search-tool.ts # thoughtbox_search — catalog query via JS
│ ├── execute-tool.ts # thoughtbox_execute — operation chaining via tb SDK
│ ├── search-index.ts # Frozen catalog of operations/prompts/resources
│ └── sdk-types.ts # TypeScript definitions for the tb SDK
├── thought/ # Thought operations and tool definitions
├── sessions/ # Session management
├── persistence/ # Storage layer
│ ├── storage.ts # InMemoryStorage with LinkedThoughtStore
│ ├── filesystem-storage.ts # FileSystemStorage with atomic writes
│ └── supabase-storage.ts # SupabaseStorage for deployed/cloud usage
├── observatory/ # Real-time visualization
│ ├── ui/ # Self-contained HTML/CSS/JS
│ └── ws-server.ts # WebSocket server for live updates
├── hub/ # Multi-agent collaboration
│ ├── identity.ts # Agent registration
│ ├── workspace.ts # Workspace management
│ ├── problems.ts # Problem tracking with dependencies
│ ├── proposals.ts # Solution proposals with reviews
│ ├── consensus.ts # Decision recording
│ ├── channels.ts # Problem-scoped messaging
│ ├── hub-handler.ts # Hub operation dispatcher
│ └── operations.ts # 28-operation catalog
├── channel/ # Hub event channels and SSE streaming
├── protocol/ # Ulysses and Theseus protocol tools
├── knowledge/ # Knowledge graph memory
├── auth/ # API key authentication
├── audit/ # Audit manifest generation
├── evaluation/ # LangSmith evaluation and online monitoring
├── notebook/ # Literate programming engine
├── events/ # Event emission system
├── observability/ # Prometheus/Grafana integration
├── prompts/ # MCP prompt definitions
├── references/ # Anchor parsing and resolution
├── revision/ # Revision indexing
├── operations-tool/ # Operations tool handler
└── resources/ # Documentation and patterns cookbook
Thoughtbox supports three storage backends:
LinkedThoughtStore for O(1) thought lookupsData is stored at ~/.thoughtbox/ by default (FileSystemStorage):
~/.thoughtbox/
├── config.json # Global configuration
└── projects/
└── {project}/
└── sessions/
└── {date}/
└── {session-id}/
├── manifest.json
└── {thought-number}.json
We welcome contributions! See CONTRIBUTING.md for:
thick_read code comprehension)MIT License — free to use, modify, and distribute.
© 2026 MCP Directory.
Extended reasoning with structured processes, persistence, and workflow guidance
{ "mcpServers": { "io.github.kastalien-research-thoughtbox": { "command": "npx", "args": [ "-y", "@kastalien-research/[email protected]" ] } }}Tools
No tool list yet. Remote servers get one after the first health check.
FAQ
Copy the stdio config for Cursor, Claude Desktop, Claude Code, or VS Code on this page. It uses the publisher's install, not a PlugMCP proxy.
No required environment variable is listed on this record.
Thoughtbox runs locally over stdio.
Last checked 2026-11-09. Extended reasoning with structured processes, persistence, and workflow guidance