The ThinkForge MCP server exposes project knowledge and bounded ThinkForge operations to external AI tools through the Model Context Protocol. It runs locally inside the desktop app on port 3001 and gives compatible clients access to indexed documents, conversations, tags, project instructions, safe document writes, and the active Mind Map's context, semantic node discovery, and revision-checked patch boundary.
What It Does
When ThinkForge is running, a server starts on http://localhost:3001. AI clients that connect to it can retrieve and maintain project instructions, search project documents using semantic similarity and keywords, read documents by path, safely update or move existing documents, repair the project index, browse tags and projects, view index statistics, save generated artifacts back into projects as real files, and semantically discover, read, or atomically update nodes in the active Mind Map.
This means working in Cursor, Claude Desktop, VS Code, Windsurf, ChatGPT Codex, or any other MCP-compatible tool gives you your ThinkForge knowledge as context without leaving that tool. The assistant can search your documents, find relevant information, and ground its responses in your own project knowledge.
Startup
The MCP server starts automatically when the desktop app launches. No user action is required.
The server starts whether or not a project is open. If no project is loaded, tools that depend on SK Memory return an error telling you to open a project. Once a project is opened and its index initializes, all tools become functional.
The server stops when ThinkForge exits.
Transport Modes
Two transport modes reach the same tools:
HTTP (direct) — Most MCP clients connect directly to http://localhost:3001. This is the primary mode for Cursor, Windsurf, VS Code Copilot, Claude Code, Cline, Roo Code, and Kiro.
Stdio bridge — Clients that require stdio launch Fire.exe --mcp-stdio, which starts a lightweight bridge process with no interface. The bridge forwards each message to the running server on port 3001 and writes responses back.
The stdio bridge has a 60-second timeout. If the main ThinkForge app is not running, it returns: "Think Forge MCP server not reachable on port 3001. Make sure Think Forge is running."
Clients that use the stdio bridge include Claude Desktop, ChatGPT Codex, and LM Studio.
Context Cost
Every tool result enters the calling client's model context, so the server returns the smallest useful response by default.
Search tools return matching chunks with identifying metadata rather than whole documents, and their default result counts are deliberately low. Full document content is available only through the explicit get_memory and get_document_by_path tools.
get_document_by_path refuses documents above a 200 KB inline read limit rather than returning them, because a single large file can otherwise consume a client's entire context window. Write tools return status and identifying metadata, never a copy of the document they just wrote.
Clients that need more can raise max_results on any search. See MCP Tools Reference for per-tool defaults and limits.
Health Check
Visiting http://localhost:3001/ in a browser returns a health check:
{
"status": "healthy",
"server": "Think Forge MCP",
"version": "1.0.0",
"port": 3001,
"sk_memory": {
"initialized": true,
"document_count": 72,
"embeddings_enabled": true
},
"tools": {
"available": 17,
"list": ["semantic_search", "hybrid_search", "..."]
}
}
The status is "healthy" when the server can query index statistics, and "degraded" when that fails — typically because no project is open.
Auto-Configuration
ThinkForge can detect installed MCP-compatible applications and write itself into their configuration files automatically. This is available from the MCP section in Settings.
ThinkForge detects a client by checking whether its configuration file or parent directory exists on disk, then writes a think-forge server entry in that client's format. Before writing to any config file for the first time, ThinkForge creates a .thinkforge.bak backup alongside it.
Ten clients are supported out of the box: Claude Desktop, Claude Code, ChatGPT Codex, Cursor, Windsurf, VS Code Copilot, Cline, Roo Code, Kiro, and LM Studio.
You can define additional clients by creating mcp-clients.user.json in the ThinkForge data directory. User definitions merge with the built-in list, and user entries win on name collisions.
See Using MCP with AI Clients for setup details and manual configuration examples.
Project Scope
The MCP server works against your active project by default. Every tool that accesses SK Memory accepts an optional project parameter naming a specific project to query instead.
The list_projects tool returns all projects on the machine. The search_all_projects tool searches across every project at once, merging and ranking results with each tagged by its source project.
Projects resolve by name against the projects root. External linked projects are also discoverable.
Project Instructions
A project may contain one optional THINKFORGE.md file in its root. The get_project_instructions tool exposes this persistent guidance to MCP clients.
ThinkForge reads the file at most once per project while the app is running. Loaded content, missing files, empty files, and failures are all cached. Restart ThinkForge after creating or changing THINKFORGE.md.
The set_project_instructions tool writes the file with conflict protection but deliberately does not refresh that cache. Its response says a restart is required.
Project instructions guide model behavior but are not an enforcement mechanism. The external client controls how the returned content is added to model context.
Error Handling
Errors occur at two levels.
Connection level — Empty or unparseable requests are rejected. Unsupported request methods are rejected.
Tool level — When a tool hits an error — a missing required parameter, a project not found, an uninitialized index — it returns the error in its response rather than failing the connection. Document changes also return explicit conflict information when the supplied content hash is stale.
Security
The server runs on localhost only. There is no authentication, no remote access, and no encryption, because it is a local-only interface into your own data.
Write tools accept project names and project-relative paths, never arbitrary absolute paths. They reject path traversal, hidden and system locations, symbolic links, stale content hashes, and documents currently open in ThinkForge. Updates use a temporary file and atomic replacement. Moves never overwrite an existing destination.
No MCP delete tool exists. An AI client cannot delete your documents.
Mind Map discovery and changes use a separate active-document boundary. The target map must be active, and calls require its exact immutable document ID. Semantic node search uses the map's SK index for ranking but rechecks live nodes before returning them. Changes require the latest map revision, validate the complete patch before touching the live map, and save through the owning Mind Map. A patch that deletes nodes or branches also requires an app-owned confirmation.
Relationship to SK Memory
The MCP server treats your physical project documents as the source of truth. Search tools query the index; creation, update, move, indexing, and reconciliation tools complete the file operation first and then wait for the index to catch up.
THINKFORGE.md is the exception — it is read directly from the project root and cached, not retrieved through the index.
Active Mind Map structure is another live authority. SK Memory ranks semantic node matches; current titles, paths, existence, context, revisions, and all changes come from the active Mind Map.
See the SK Memory section for how documents get indexed, chunked, and embedded.