Skip to main content
This guide helps you diagnose and resolve common issues when installing and running Model Context Protocol (MCP) servers, including missing environments, server initialization failures, and configuration errors.

​
Failed to add or install the MCP servers

​
Issue: NPX environment missing

​
Error message

failed to start command: exec: "npx": executable file not found in $PATH

​
Cause

The npx command-line tool, part of the Node.js ecosystem, is not installed or not accessible in your system’s PATH.

​
Solution

Install Node.js V18 or later (which includes NPM V8+ ). Earlier versions may cause tool failures.

​
Installation steps

  • Windows
Install nvm-windows to manage multiple versions: 
nvm install 22.14.0  # Install a specified version.
nvm use 22.14.0
Verify the installation. 
node -v
npx -v
Then, the terminal will display the installed Node.js version number.
  • macOS
Use Homebrew (install first if needed). 
 # 1. Update Homebrew and install Node.js.
brew update
brew install node

    # 2. Verify installation and confirm the versions.
echo "Node.js version: $(node -v)"
echo "npm version: $(npm -v)"
echo "npx version: $(npx -v)"

# 3. Configure environment variables (if necessary).
echo 'export PATH="/usr/local/opt/node@16/bin:$PATH"' >> ~/.zshrc

​
Issue: UVX environment missing

​
Error message

failed to start command: exec: "uvx": executable file not found in $PATH

​
Cause

The uvx command, used to run Python scripts in isolated environments via uv, is not installed.

​
Solution

Install uv, a fast Python package installer and virtual environment manager. Installation steps
  • Windows
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
  • macOS and Linux
curl -LsSf https://astral.sh/uv/install.sh | sh
Verify the installation. 
uv --version
Then, the terminal will display the installed uv version number.

​
Issue: Unable to initialize MCP Client

​
Error message

failed to initialize MCP client: context deadline exceeded

​
Possible causes

  • Incorrect MCP servers parameters
  • Network issues preventing resource download
  • Corporate network security policies blocking initialization

​
Solution

  1. Click Copy complete command in the UI.
  2. Run the command in the terminal to get detailed error output. 5eecdaf48460cde54c3c3804ffe8bf87ad3cbe07b57fd6f075b8339e1c4c24831b75b38faadcd24bec177c308ebd53044ba5cb417a050fa713573df52e9556d73089d0c5ebddcce6fb457c16604993997e5e3b8f420e29e64fb4c8ed7016461c Pn
  3. Analyze and resolve based on the specific error.
Common issue 1: Configuration error The error may indicate an invalid configuration, such as an incorrect Redis connection URL. Fix: Review and correct the configuration in the MCP servers settings. Common issue 2: Node.js blocked by security software Corporate security tools may block Node.js execution. Fix: Add Node.js or the relevant process to the whitelist in your security software.

​
Tool usage issues

​
Issue: Tools fail due to environment or parameter errors

​
Symptoms

Unexpected behavior or errors when calling MCP tools.

​
Cause

Some MCP servers (e.g., MasterGo, Figma) require manual configuration of API_KEY or TOKEN in the arguments during setup.

​
Solution

  1. In the upper-left corner of your Qoder IDE, click the user icon or use the keyboard shortcut (⌘ ⇧ , （macOS）orCtrl shift ,(Windows)), and select Qoder Settings.
  2. In the left-side navigation pane, click MCP.
  3. Find the relevant server and click Edit.
  4. In the Edit MCP Server page, check the parameters in Arguments.
  5. Replace with correct values, reconnect the server, and retry.

​
Issue: LLM fails to call MCP tools

Cause 1: Not in Agent mode If no project directory is open, Qoder defaults to Ask mode, which does not support MCP tool calls. Fix: Open a project directory and switch to Agent mode. Cause 2: MCP server not connected A disconnected server prevents tool invocation. Fix: Click Retry icon in the interface. The system will attempt to restart the MCP server automatically.
Best Practice: Avoid naming MCP servers and their tools too similarly (for example, both TextAnalyzer-Pro and TextAnalyzer-Plus having a fetchText tool), to prevent ambiguity during calls.

​
Issue: MCP server list fails to load

​
Symptoms

The server list shows a continuous loading state.

​
Solution

Restart the Qoder IDE and try again.
⌘I