How to Troubleshoot MCP Connection Issues on Windows: A Complete Guide

The most common cause of MCP connection failures on Windows is path separator mismatches in .mcp.json or launching the server from the wrong working directory, both of which prevent the FastMCP server from locating your knowledge graph.

The MCP (Model-Content-Protocol) server in the tirth8205/code-review-graph repository acts as the bridge between AI-assisted tools like Claude Code and your local code-review knowledge base. When you troubleshoot MCP connection issues on Windows, you are typically diagnosing why this FastMCP-based server cannot establish its stdio pipe or HTTP connection to the client. Understanding the Windows-specific quirks of this architecture is essential for resolving connection failures quickly.

Understanding the MCP Architecture on Windows

The MCP server implementation resides in code_review_graph/mcp_server.py and provides asynchronous RPC endpoints for over 30 graph-querying tools. On Windows, the server operates in one of two transport modes:

• stdio mode: The default for Claude Code, using piped standard input/output for low-latency communication
• HTTP mode: A localhost service useful for IDE plugins and custom integrations

According to the source code in tirth8205/code-review-graph, the server relies on Python's asyncio and ThreadPoolExecutor to handle concurrent requests. A critical Windows-specific optimization exists where the server pre-warms local embedding models before accepting connections to prevent deadlocks in the worker pool, as documented in the Windows MCP reliability section of docs/FEATURES.md.

Common Windows-Specific Failure Modes

Path Separator Errors in .mcp.json

The .mcp.json configuration file stores the absolute path to your Python interpreter and working directory at install time. On Windows, a common failure occurs when this file contains backslash-separated paths (C:\Users\...), which break the MCP launcher. All paths must use forward slashes (C:/Users/...) to be parsed correctly by the FastMCP transport layer.

Working Directory Mismatches

The server expects to be launched from your project root where .code-review-graph/graph.db exists. If you invoke the CLI from a parent or sibling directory, the server initializes successfully but returns "graph not found" errors because it searches the wrong location for the database. Always run commands from the directory containing .mcp.json, or explicitly pass --repo-root <path>.

Python Interpreter Mismatches

When you run code-review-graph install, the active Python interpreter path is hardcoded into .mcp.json. If you later switch virtual environments without reinstalling, the MCP server attempts to launch using the old interpreter, which may lack required dependencies or point to a non-existent environment.

Semantic Search Deadlocks

Before the Windows reliability fix, invoking semantic search tools could cause the FastMCP worker pool to deadlock if the embedding model wasn't loaded. While current versions pre-warm models automatically, stale installations may still exhibit this behavior. This manifests as the server accepting connections but hanging indefinitely on the first semantic query.

Step-by-Step Diagnostic Checklist

Follow these steps in order when troubleshooting connection failures:

1. Verify .mcp.json exists at your project root and contains forward-slash paths (/ not \).

2. Restart your AI client (Claude Code, CodeBuddy, etc.) after any installation or configuration change, as clients read .mcp.json only at startup.

3. Check server status by running:

   code-review-graph mcp status

   You should see ✅ MCP server is running (stdio).

4. Inspect logs if the server fails to start:

   type %USERPROFILE%\AppData\Local\Claude\mcp.log | findstr "ERROR"

5. Validate your working directory matches the project root specified in .mcp.json.

6. Force a fresh connection by restarting the server:

   code-review-graph mcp restart

   Then quit and relaunch your AI client.

Inspecting Logs and Debugging

When the MCP server fails silently, check %USERPROFILE%\AppData\Local\Claude\mcp*.log for stack traces. These logs capture FastMCP initialization errors, missing module imports, and path resolution failures.

Inside Claude Code, use the debug command:

/mcp

This displays the current connection status and any error dumps from failed server launches. If you see ⛔️ MCP server not running – run code-review-graph mcp start first, the server process never initialized.

Fixing Path and Configuration Issues

To resolve path-related failures, reinstall the MCP server while ensuring your virtual environment is active:

# Activate your environment first

$ uv pip install -e .
$ code-review-graph install

This rewrites .mcp.json with the correct interpreter path and converts Windows paths to the required forward-slash format. The code-review-graph install command automatically handles path normalization for the Windows platform.

Resolving Deadlocks and Server Crashes

If semantic search queries cause the server to hang, your embedding models may need reinstallation:

code-review-graph embed install
code-review-graph mcp restart

This ensures the pre-warm step executes correctly, loading the embedding model into memory before the ThreadPoolExecutor begins accepting requests. The regression test in tests/test_mcp_stdio_shutdown.py validates that the server shuts down cleanly after these operations, confirming your fix works.

Summary

• Use forward slashes in .mcp.json paths to prevent parser failures on Windows
• Launch from the project root or use --repo-root to ensure the server finds graph.db
• Restart AI clients after running code-review-graph install to pick up new configurations
• Check logs at %USERPROFILE%\AppData\Local\Claude\mcp*.log for detailed error traces
• Reinstall the embed component if semantic searches deadlock the worker pool

Frequently Asked Questions

Why does my MCP server fail to start after installation?

The most likely cause is that your AI client was running when you executed code-review-graph install. Clients cache the .mcp.json configuration at startup, so they won't see newly installed servers. Quit and relaunch Claude Code or your IDE completely. Additionally, verify that the Python interpreter path in .mcp.json points to your current virtual environment, not a deleted or moved one.

How do I fix path errors in .mcp.json on Windows?

Run code-review-graph install from your project root while your virtual environment is active. This regenerates the configuration file with properly formatted paths. If editing manually, convert all backslashes to forward slashes (e.g., change C:\Users\name\project to C:/Users/name/project) and ensure the path uses absolute rather than relative references.

What causes the semantic search deadlock on Windows?

The deadlock occurs when the FastMCP worker pool attempts to use embedding models that haven't been loaded into memory. On Windows, the ThreadPoolExecutor can freeze if a worker blocks on I/O before the pool initializes fully. The current version pre-warms models automatically, but you can trigger this manually by running code-review-graph embed install followed by a server restart.

Where are MCP server logs stored on Windows?

Logs are written to %USERPROFILE%\AppData\Local\Claude\mcp.log (and dated variants like mcp-2024-01-15.log). Use the Windows command type %USERPROFILE%\AppData\Local\Claude\mcp.log | findstr "ERROR" to filter for errors, or open the file directly in your text editor to see the complete FastMCP startup sequence and any traceback information.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}