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

> Solve MCP connection issues on Windows fast. Learn common causes like path separator mismatches and incorrect server launches to fix your FastMCP server.

- Repository: [Tirth Kanani/code-review-graph](https://github.com/tirth8205/code-review-graph)
- Tags: how-to-guide
- Published: 2026-07-25

---

**The most common cause of MCP connection failures on Windows is path separator mismatches in [`.mcp.json`](https://github.com/tirth8205/code-review-graph/blob/main/.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`](https://github.com/tirth8205/code-review-graph/blob/main/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](https://github.com/tirth8205/code-review-graph/blob/main/docs/FEATURES.md#windows-mcp-reliability) section of [`docs/FEATURES.md`](https://github.com/tirth8205/code-review-graph/blob/main/docs/FEATURES.md).

## Common Windows-Specific Failure Modes

### Path Separator Errors in .mcp.json

The [`.mcp.json`](https://github.com/tirth8205/code-review-graph/blob/main/.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`](https://github.com/tirth8205/code-review-graph/blob/main/.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`](https://github.com/tirth8205/code-review-graph/blob/main/.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`](https://github.com/tirth8205/code-review-graph/blob/main/.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`](https://github.com/tirth8205/code-review-graph/blob/main/.mcp.json) only at startup.

3. **Check server status** by running:
   ```bash
   code-review-graph mcp status
   ```

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

4. **Inspect logs** if the server fails to start:
   ```cmd
   type %USERPROFILE%\AppData\Local\Claude\mcp.log | findstr "ERROR"
   ```

5. **Validate your working directory** matches the project root specified in [`.mcp.json`](https://github.com/tirth8205/code-review-graph/blob/main/.mcp.json).

6. **Force a fresh connection** by restarting the server:
   ```bash
   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:

```text
/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:

```bash

# Activate your environment first

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

```

This rewrites [`.mcp.json`](https://github.com/tirth8205/code-review-graph/blob/main/.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:

```bash
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`](https://github.com/tirth8205/code-review-graph/blob/main/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`](https://github.com/tirth8205/code-review-graph/blob/main/.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`](https://github.com/tirth8205/code-review-graph/blob/main/.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`](https://github.com/tirth8205/code-review-graph/blob/main/.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.