Using MCP with AI Clients

The ThinkForge MCP server works with any tool that supports the Model Context Protocol. This document covers which clients are supported, how to configure them, and how to verify the connection.

Supported Clients

ThinkForge auto-configuration supports ten clients out of the box. They connect in two modes:

HTTP clients connect directly to the MCP server URL at http://localhost:3001:

  • Cursor
  • Windsurf
  • VS Code (Copilot)
  • Claude Code
  • Cline (VS Code extension)
  • Roo Code (VS Code extension)
  • Kiro

Stdio clients are launched via Fire.exe --mcp-stdio, which bridges stdin/stdout to the HTTP server:

  • Claude Desktop
  • ChatGPT / Codex
  • LM Studio

Any other MCP-compatible client can be configured manually using either transport mode.

Auto-Configuration

ThinkForge can detect installed clients and configure the connection automatically.

  1. Open ThinkForge settings
  2. Navigate to the MCP section
  3. The settings panel shows detected clients with their configuration status
  4. Use the configure option to write the server entry into each client's config file

ThinkForge detects a client by checking whether its configuration file or parent directory exists on disk. A client is marked as "configured" when its config file already contains a think-forge server entry.

Before writing to any config file for the first time, ThinkForge creates a .thinkforge.bak backup alongside it. The backup is created once per file and is not overwritten on subsequent configuration updates.

If ThinkForge cannot parse an existing config file (corrupted JSON, unexpected format), it aborts without writing and reports the error. It never overwrites a config file with an empty or partial document.

Manual Configuration

For clients not detected by auto-configuration, or when you prefer manual setup:

Cursor

Add to .cursor/mcp.json in your workspace or home directory:

{
  "mcpServers": {
    "think-forge": {
      "url": "http://localhost:3001"
    }
  }
}

VS Code (Copilot)

Add to .vscode/mcp.json or VS Code settings:

{
  "servers": {
    "think-forge": {
      "type": "http",
      "url": "http://localhost:3001"
    }
  }
}

Windsurf

Add to Windsurf's MCP configuration:

{
  "mcpServers": {
    "think-forge": {
      "serverUrl": "http://localhost:3001"
    }
  }
}

Note: Windsurf uses serverUrl rather than url.

Claude Desktop

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "think-forge": {
      "command": "C:\\path\\to\\Fire.exe",
      "args": ["--mcp-stdio"]
    }
  }
}

Replace the path with the actual location of Fire.exe on your machine.

ChatGPT Codex

Add to the Codex TOML configuration:

[mcp_servers.think-forge]
command = 'C:\path\to\Fire.exe'
args = ["--mcp-stdio"]

Claude Code

Add to Claude Code's MCP configuration:

{
  "mcpServers": {
    "think-forge": {
      "type": "http",
      "url": "http://localhost:3001"
    }
  }
}

Requirements

ThinkForge must be running for the MCP server to be available. The server starts automatically with the desktop app on port 3001.

For stdio clients (Claude Desktop, Codex, LM Studio), the main ThinkForge app must already be running because the stdio bridge forwards requests to the HTTP server inside the app. If ThinkForge is not running, stdio clients will receive an error: "Think Forge MCP server not reachable on port 3001. Make sure Think Forge is running."

A project must be open in ThinkForge for most tools to function. If no project is loaded, tools return: "SK Memory is not initialized. Open a project in Fire first."

Verifying the Connection

To verify the MCP server is running and reachable:

From a browser or curl: Visit http://localhost:3001/ — this returns a JSON health check showing server status, SK Memory state, document count, embedding status, and available tools. A "status": "healthy" response confirms the server is fully operational.

From an AI client: Ask the assistant to call list_projects. If it returns a list of your Fire projects, the connection is working. If it returns an error about SK Memory not being initialized, ThinkForge is running but no project is open.

Common issues:

  • Client cannot connect: ThinkForge is not running. Start the app and wait a few seconds for the MCP server to initialize.
  • Tools return SK Memory errors: A project needs to be opened in ThinkForge.
  • Stdio bridge fails immediately: The main ThinkForge app must be running before launching Fire.exe --mcp-stdio. The bridge forwards to the HTTP server and cannot function standalone.
  • Client not detected by auto-config: The client's config directory may not exist yet. Open the client at least once to create its configuration directory, then retry auto-configuration. Alternatively, configure manually.
  • Config file not writable: Close the client application before running auto-configuration, or configure manually.

Adding Custom Clients

If your MCP client is not in the built-in catalog, you can add it by creating or editing mcp-clients.user.json in the ThinkForge data directory.

Each entry defines:

  • Name — Display name for the settings UI
  • Kind — "url" for HTTP clients, "command" for stdio clients
  • Format — "json" or "toml"
  • Path — Config file path with tokens ({USERPROFILE}, {APPDATA}, {LOCALAPPDATA})
  • Container — JSON/TOML key that holds the server map (e.g., mcpServers, servers, mcp_servers)
  • UrlField — For URL-kind clients: "url" or "serverUrl"
  • Extra — Additional fields to include in the server entry (e.g., { "type": "http" })

User-defined clients merge with the built-in catalog. If a user entry has the same name as a built-in client, the user definition takes precedence.

The ThinkForge MCP settings panel shows available presets (standard HTTP, VS Code style, Windsurf style, stdio JSON, Codex TOML) to help structure new client definitions.

What Clients Can Do

Once connected, an AI client has access to the full tool catalog:

  • get_project_instructions for persistent guidance about how to work with a project
  • set_project_instructions for safely creating or replacing THINKFORGE.md
  • hybrid_search and semantic_search for finding relevant context using natural language
  • search_all_projects for searching across every project simultaneously
  • tag_search for finding documents by tag
  • get_memory for reading full documents and their indexed chunks
  • get_document_by_path and update_document for hash-guarded edits to existing physical documents
  • move_document for guarded in-project moves and renames that preserve navigation references
  • index_document and reconcile_project for repairing or synchronizing SK Memory
  • list_projects and list_tags for browsing available content
  • get_statistics for understanding the index state
  • save_artifact and save_artifacts for persisting generated content back into projects

See the MCP Tools Reference for complete parameter and response documentation.

Typical Workflow

A common pattern when using ThinkForge MCP from a coding assistant:

  1. The AI calls list_projects to see available projects
  2. The AI calls get_project_instructions once for the relevant project and follows any returned instructions
  3. The AI uses hybrid_search with that project to find context for the current task
  4. The AI reads full documents with get_memory (with include_chunks: true) when deeper context is needed
  5. The AI uses project knowledge to inform its work
  6. New generated documentation or artifacts are saved with save_artifact
  7. Existing canonical documents are read with get_document_by_path and revised with update_document, passing the returned hash

This workflow means the AI never starts from zero. The user's accumulated project knowledge is always available as grounding context.