> ## Documentation Index
> Fetch the complete documentation index at: https://docs.qoder.com/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP Common Issues

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](https://nodejs.org/) V18 or later (which includes NPM V8+ ). Earlier versions may cause tool failures.

#### **Installation steps**

* Windows

Install [nvm-windows](https://github.com/coreybutler/nvm-windows) to manage multiple versions:

```shellscript theme={null}
nvm install 22.14.0  # Install a specified version.
nvm use 22.14.0
```

Verify the installation.

```shellscript theme={null}
node -v
npx -v
```

Then, the terminal will display the installed Node.js version number.

* **macOS**

Use Homebrew (install first if needed).

```shellscript theme={null}
 # 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

```shellscript theme={null}
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
```

* macOS and Linux

```shellscript theme={null}
curl -LsSf https://astral.sh/uv/install.sh | sh
```

Verify the installation.

```shellscript theme={null}
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.

   <img src="https://mintcdn.com/qoder/soy4sNOQCG_ZPrfN/images/5eecdaf48460cde54c3c3804ffe8bf87ad3cbe07b57fd6f075b8339e1c4c24831b75b38faadcd24bec177c308ebd53044ba5cb417a050fa713573df52e9556d73089d0c5ebddcce6fb457c16604993997e5e3b8f420e29e64fb4c8ed7016461c.png?fit=max&auto=format&n=soy4sNOQCG_ZPrfN&q=85&s=291f3c7d55c50872af3c920ea4fc74ad" alt="5eecdaf48460cde54c3c3804ffe8bf87ad3cbe07b57fd6f075b8339e1c4c24831b75b38faadcd24bec177c308ebd53044ba5cb417a050fa713573df52e9556d73089d0c5ebddcce6fb457c16604993997e5e3b8f420e29e64fb4c8ed7016461c Pn" width="1440" height="336" data-path="images/5eecdaf48460cde54c3c3804ffe8bf87ad3cbe07b57fd6f075b8339e1c4c24831b75b38faadcd24bec177c308ebd53044ba5cb417a050fa713573df52e9556d73089d0c5ebddcce6fb457c16604993997e5e3b8f420e29e64fb4c8ed7016461c.png" />
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）or`Ctrl` `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.