Resolved

MCP server connection fails with ModuleNotFoundError and env parsing issues

Python
MCP
Configuration
Debugging
Dependency Management
Poetry
CLI
Server

Azure-rag MCP server in Claude Code/CLI fails to connect due to missing Python dependencies, malformed .env configuration, and incorrect entry point imports | Multiple interdependent issues prevent server initialization despite valid codebase

Issue

The MCP server encountered multiple critical initialization errors when attempting to start in Claude Code. Key issues included missing dependencies, malformed environment configurations, and incorrect entry point usage, preventing the server from functioning properly.

Culprit

  1. Missing Dependencies: The project lacked required packages for tree-sitter, which were necessary for AST-aware code chunking in the RAG pipeline.
  2. Environment File Errors: The .env file contained JSON arrays that were incompatible with bash sourcing, causing syntax errors. Additionally, field names used double underscores instead of the single underscores expected by the configuration parser.
  3. Incorrect Configuration: The .mcp.json configuration attempted to use bash to source the malformed .env file and incorrectly referenced a non-existent entry point (run_server.py) that did not match the actual implementation in src/server.py.
  4. Wrong Server Entry Point: The run_server.py file attempted to import non-existent classes, while the actual server implementation was correctly defined in src/server.py.

Solution

The issues were resolved through the following steps:

  1. Dependency Resolution: Missing tree-sitter packages were added to the project dependencies, ensuring all required tools for AST-aware chunking were available.
  2. Environment Configuration Fix: A properly formatted .env.mcp file was created, using single underscores and simple values instead of JSON arrays. This ensured compatibility with the configuration parser.
  3. MCP Configuration Update: The .mcp.json file was modified to use Poetry directly for execution, eliminating the need to source the environment file and ensuring correct module imports.
  4. Correct Entry Point Usage: The server initialization was updated to use the actual entry point in src/server.py, which included the correct server implementation.

These changes resolved the initialization errors, allowing the MCP server to start successfully and connect to ChromaDB, enabling hybrid search functionality and access to the indexed Bloomberg articles.