> ## 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 の一般的な問題

このガイドでは、環境変数の不足、サーバーの初期化失敗、設定ミスなど、Model Context Protocol（MCP）サーバーのインストールや実行時によく発生する問題の診断と解決方法を説明します。

<div id="failed-to-add-or-install-the-mcp-servers">
  ## **MCP サーバーの追加またはインストールに失敗**
</div>

<div id="issue-npx-environment-missing">
  ### **問題: NPX 環境が見つからない**
</div>

<div id="error-message">
  #### **エラーメッセージ**
</div>

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

<div id="cause">
  #### **原因**
</div>

Node.js エコシステムの一部である `npx` コマンドラインツールが、システムの `PATH` にインストールされていないか、`PATH` から参照できません。

<div id="solution">
  #### **解決策**
</div>

[Nnode.js](https://nodejs.org/) の V18 以降をインストールしてください（NPM V8 以上が含まれます）。それ以前のバージョンではツールが正常に動作しない場合があります。

<div id="installation-steps">
  #### **インストール手順**
</div>

* Windows

複数バージョンを管理するには、[nvm-windows](https://github.com/coreybutler/nvm-windows) をインストールします：

```shellscript theme={null}
nvm install 22.14.0  # 指定したバージョンをインストール
nvm use 22.14.0
```

インストールを確認します。

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

その後、ターミナルにインストール済みの Node.js のバージョン番号が表示されます。

* **macOS**

Homebrew を使用します（未導入の場合は先にインストールしてください）。

```shellscript theme={null}
 # 1. Homebrewを更新してNode.jsをインストールします。
brew update
brew install node

    # 2. インストールを確認してバージョンを確認します。
echo "Node.jsバージョン: $(node -v)"
echo "npmバージョン: $(npm -v)"
echo "npxバージョン: $(npx -v)"

# 3. 環境変数を設定します（必要に応じて）。
echo 'export PATH="/usr/local/opt/node@16/bin:$PATH"' >> ~/.zshrc
```

<div id="issue-uvx-environment-missing">
  ### **問題: UVX 環境が見つからない**
</div>

<div id="error-message">
  #### **エラーメッセージ**
</div>

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

<div id="cause">
  #### **原因**
</div>

`uv` を使って隔離環境で Python スクリプトを実行するための `uvx` コマンドがインストールされていません。

<div id="solution">
  #### **解決方法**
</div>

高速な Python パッケージインストーラー兼仮想環境マネージャーである `uv` をインストールします。

**インストール手順**

* Windows

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

* macOS および Linux

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

インストールを検証する

```shellscript theme={null}
uv --version
```

すると、ターミナルにインストール済みの uv のバージョン番号が表示されます。

<div id="issue-unable-to-initialize-mcp-client">
  ### **問題: MCP クライアントを初期化できない**
</div>

<div id="error-message">
  #### **エラーメッセージ**
</div>

`MCP クライアントの初期化に失敗しました: context の期限を超過しました`

<div id="possible-causes">
  #### **考えられる原因**
</div>

* MCP サーバーのパラメータが不正
* リソースのダウンロードを妨げるネットワーク障害
* 初期化を阻止する企業ネットワークのセキュリティポリシー

<div id="solution">
  #### **解決策**
</div>

1. UIで**Copy complete command**をクリックします。
2. ターミナルでコマンドを実行し、詳細なエラー出力を確認します。

   <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. 出力された具体的なエラーに基づいて分析・対処します。

**よくある問題 1**: 設定エラー

エラーが、Redis の接続URLの誤りなど、無効な設定を示している場合があります。

対処: MCP サーバー設定を見直し、正しく修正します。

**よくある問題 2**: セキュリティソフトによる Node.js のブロック

企業向けのセキュリティツールが Node.js の実行をブロックする場合があります。

対処: セキュリティソフトの許可リストに Node.js または該当プロセスを追加します。

<div id="tool-usage-issues">
  ## **ツールの利用に関する問題**
</div>

<div id="issue-tools-fail-due-to-environment-or-parameter-errors">
  ### **問題: 環境設定またはパラメータの不備によりツールが失敗する**
</div>

<div id="symptoms">
  #### **症状**
</div>

MCP ツール呼び出し時に、想定外の挙動やエラーが発生する。

<div id="cause">
  #### **原因**
</div>

一部の MCP サーバー（例：MasterGo、Figma）では、セットアップ時に引数で `API_KEY` または `TOKEN` を手動で設定する必要があります。

<div id="solution">
  #### **解決策**
</div>

1. Qoder IDE の左上のユーザーアイコンをクリックするか、キーボードショートカット（`⌘` `⇧` `,`（macOS）または `Ctrl` `Shift` `,`（Windows））を使って、**Qoder 設定**を選択します。
2. 左側のナビゲーションペインで **MCP** をクリックします。
3. 対象のサーバーを見つけて **Edit** をクリックします。
4. **Edit MCP Server** ページで、**Arguments** のパラメーターを確認します。
5. 正しい値に置き換え、サーバーに再接続して再試行します。

<div id="issue-llm-fails-to-call-mcp-tools">
  ### **問題: LLM が MCP ツールの呼び出しに失敗する**
</div>

**原因 1:** Agent モードではない

プロジェクトディレクトリが開かれていない場合、Qoder はデフォルトで Ask Mode になり、MCP ツールの呼び出しはサポートされません。

**対処:** プロジェクトディレクトリを開き、Agent モードに切り替えてください。

**原因 2:** MCP サーバーが未接続

サーバーが切断されていると、ツールを呼び出せません。

**対処**: インターフェースの Retry アイコンをクリックしてください。システムが自動的に MCP サーバーの再起動を試みます。

> **ベストプラクティス:** 呼び出し時の曖昧さを避けるため、MCP サーバーおよびツールに類似しすぎる名前を付けないでください（例: `TextAnalyzer-Pro` と `TextAnalyzer-Plus` の両方に `fetchText` ツールがある場合）。

<div id="issue-mcp-server-list-fails-to-load">
  ### **問題: MCP サーバーリストを読み込めない**
</div>

#### 症状

サーバー一覧が読み込み中のままになっている。

<div id="solution">
  #### **解決策**
</div>

Qoder IDE を再起動して、もう一度お試しください。