Problemy z połączeniem serwera MCP

Dodałeś Postgres MCP, zrestartowałeś Cursora, a lista narzędzi nadal jest pusta i obok serwera świeci czerwona kropka. Albo Claude Code wypisuje spawn npx ENOENT w chwili, gdy próbuje uruchomić serwer. Albo połączenie działa na Twojej maszynie, ale kolega z zespołu za każdym razem dostaje Client closed. Awarie połączeń MCP to prawie zawsze jedna z czterech rzeczy: nie można znaleźć binarki, brakuje zmiennej środowiskowej, token uwierzytelniający jest błędny lub wygasł albo transport nigdy nie kończy handshake’u.

Ten przewodnik przeprowadza diagnozę po kolei, daje gotowe do wklejenia prompty, które sprawiają, że sam agent ujawnia prawdziwy błąd, i obejmuje poprawki specyficzne dla systemu (PATH, Gatekeeper, firewalle), które oficjalna dokumentacja pomija.

Czego się nauczysz

• Pięciokrokowej kolejności diagnostycznej, która izoluje awarię, zanim zaczniesz zgadywać
• Promptów do skopiowania, które sprawiają, że Cursor, Claude Code albo Codex raportują dokładny stderr z padającego serwera
• Prawdziwych poprawek na spawn ENOENT, nieaktualny cache npx i brakujące wpisy PATH
• Gdzie każde narzędzie zapisuje swoje logi MCP i jak je czytać
• Poprawek specyficznych dla platform: macOS Gatekeeper, polityka wykonywania Windows i uprawnienia Linux

Diagnozuj po kolei

Problemy z połączeniem wydają się losowe, dopóki nie sprawdzisz ich we właściwej kolejności. Każdy krok wyklucza całą klasę przyczyn.

1. Czy serwer w ogóle się uruchamia? Uruchom dokładną komendę startową z konfiguracji w zwykłym terminalu. Jeśli tam padnie, padnie też wewnątrz klienta.
2. Czy binarka jest na PATH? Aplikacje GUI (Cursor) i powłoki logowania mają często inny PATH niż Twój interaktywny terminal. spawn ENOENT prawie zawsze oznacza, że klient nie może znaleźć npx/node/uvx.
3. Czy dane uwierzytelniające są obecne i prawidłowe? Brakujące zmienne środowiskowe i wygasłe tokeny OAuth objawiają się jako “połączony, ale brak narzędzi” albo “permission denied”.
4. Czy rejestracja narzędzi się zakończyła? Serwer może się połączyć i nadal reklamować zero narzędzi, jeśli padł podczas inicjalizacji. Przeczytaj stderr.
5. Czy transport jest zdrowy? Dla serwerów zdalnych/HTTP sprawdź URL, firewall i ewentualne firmowe proxy.

”No Tools Found” lub serwer niewidoczny

Najczęstszy objaw: serwer pojawia się w konfiguracji, ale pokazuje czerwoną kropkę błędu i nie wnosi żadnych narzędzi.

Cursor

Symptomy: czerwony wskaźnik obok serwera, “No tools found”, serwer nieobecny na liście narzędzi.

# 1. Zweryfikuj poprawność JSON-a konfiguracji (przecinek na końcu po cichu psuje cały plik)
cat ~/.cursor/mcp.json        # globalny, lub .cursor/mcp.json w projekcie

# 2. Uruchom komendę startową serwera ręcznie, żeby zobaczyć prawdziwe błędy
npx -y postgres-mcp

# 3. Całkowicie zamknij i otwórz Cursora ponownie (Cmd/Ctrl+Q, nie tylko zamknięcie okna)

Minimalny, prawidłowy wpis stdio — schemat Cursora wspiera tylko command/args/env dla stdio oraz url/headers dla serwerów zdalnych:

{
  "mcpServers": {
    "postgres": {
      "command": "npx",
      "args": ["-y", "postgres-mcp"],
      "env": { "DATABASE_URL": "${DATABASE_URL}" }
    }
  }
}

Claude Code

Symptomy: serwer nieobecny na liście narzędzi, brak narzędzi MCP w chacie, timeout połączenia.

# 1. Wylistuj skonfigurowane serwery i ich rozpoznany status
claude mcp list

# 2. Sprawdź komendę, args i env jednego serwera
claude mcp get postgres

# 3. Uruchom ponownie z logowaniem debug MCP
claude --debug "mcp"

Wewnątrz REPL /mcp pokazuje status połączenia na żywo i pozwala interaktywnie ponownie połączyć lub uwierzytelnić serwer.

Codex

Symptomy: serwer wylistowany w konfiguracji, ale brak dostępnych narzędzi, albo w ogóle nie pojawia się pod /mcp.

Codex przechowuje serwery w ~/.codex/config.toml pod [mcp_servers.<name>]:

# 1. Wylistuj skonfigurowane serwery (dodaj --json dla surowego wyjścia)
codex mcp list

# 2. Sprawdź rozpoznaną konfigurację jednego serwera
codex mcp get postgres

# 3. Przeczytaj najnowszy log po odtworzeniu awarii
tail -n 100 ~/.codex/log/codex-tui.log

Wewnątrz TUI /mcp listuje aktywne serwery i to, ile narzędzi każdy załadował. Wpis stdio w config.toml wygląda tak:

[mcp_servers.postgres]
command = "npx"
args = ["-y", "postgres-mcp"]

[mcp_servers.postgres.env]
DATABASE_URL = "postgres://localhost/app"

Wskazówka

Prompt do skopiowania — serwer z czerwoną kropką w Cursorze:

“My postgres MCP server shows a red dot and no tools in Cursor. Read my ~/.cursor/mcp.json, validate that it is well-formed JSON, then run the server’s exact launch command in a terminal and report the precise stderr. Tell me whether the failure is a JSON syntax error, a missing binary on PATH, or a missing environment variable."

"Client Closed” lub “spawn ENOENT”

Te błędy oznaczają, że proces serwera nigdy się nie uruchomił. Binarki uruchamiającej brakuje w PATH klienta albo nie udało się rozwiązać pakietu.

# Wyczyść zepsuty cache npx, a potem rozwiąż ponownie
npx clear-npx-cache

# Potwierdź binarki uruchamiające, których użyje klient
node --version       # aktywny Node LTS, np. 22.x
npx --version

# Uruchom komendę serwera bezpośrednio — najszybszy sposób, by zobaczyć prawdziwy błąd
npx -y postgres-mcp

Niedopasowanie PATH to zwykły winowajca: aplikacja GUI dziedziczy PATH logowania systemu, a nie dodatki z Twojego .zshrc/.bashrc.

macOS / Linux

# Znajdź, gdzie naprawdę mieszka node, a potem upewnij się, że klient go widzi
which node            # np. /Users/you/.nvm/versions/node/v22.14.0/bin/node

# Jeśli używasz nvm/asdf, wskaż w konfiguracji ścieżkę bezwzględną zamiast gołego "npx":
# "command": "/Users/you/.nvm/versions/node/v22.14.0/bin/npx"

Instalacje przez menedżery wersji to przyczyna spawn ENOENT numer jeden w klientach GUI, bo shim jest na PATH tylko wewnątrz interaktywnej powłoki. Albo uruchom GUI z terminala, w którym menedżer wersji jest załadowany, albo wpisz na sztywno ścieżkę bezwzględną do npx/node w konfiguracji.

Windows

# Potwierdź, że Node jest na PATH dla użytkownika uruchamiającego klienta
where.exe node

# Jeśli npx się nie rozwiązuje, wskaż w konfiguracji node + bezwzględną ścieżkę skryptu:

{
  "mcpServers": {
    "server-name": {
      "command": "node",
      "args": ["C:\\Users\\You\\AppData\\Roaming\\npm\\node_modules\\<scope>\\<server>\\dist\\index.js"]
    }
  }
}

W JSON używaj podwójnych ukośników wstecznych. Jeśli wyskakują okna PowerShella, ustaw "windowsHide": true we wpisie serwera w Cursorze.

Wskazówka

Prompt do skopiowania — awaria spawn w Claude Code:

“Run claude mcp get postgres, then launch that exact command directly in my shell. Tell me which of these is the cause: (a) spawn ENOENT because npx/node is not on PATH, (b) a missing required environment variable, or (c) an authentication failure from the underlying API. Give me the one-line fix for whichever it is.”

Awarie uwierzytelniania i uprawnień

Połączony serwer z zerową liczbą narzędzi albo “permission denied” przy każdym wywołaniu to prawie zawsze problem z poświadczeniami: brakująca zmienna env, wygasły token OAuth albo token o zbyt wąskim zakresie.

Cursor

Odwołuj się do sekretów ze środowiska, zamiast wpisywać je na sztywno. Wyeksportuj zmienną w profilu powłoki, a potem ją wstaw:

{
  "mcpServers": {
    "api-server": {
      "command": "npx",
      "args": ["-y", "@example/server"],
      "env": { "API_KEY": "${MY_API_KEY}" }
    }
  }
}

Dla zdalnych serwerów opartych na OAuth Cursor otwiera przepływ w przeglądarce przy pierwszym połączeniu — sprawdź, czy żaden bloker popupów go nie połyka i czy URL przekierowania serwera jest na białej liście.

Claude Code

# Serwer zdalny/OAuth: dodaj go, a potem dokończ przepływ w przeglądarce
claude mcp add --transport http github https://api.githubcopilot.com/mcp/

# Ponownie wywołaj uwierzytelnianie z REPL, jeśli token wygasł
/mcp

Jeśli token wygasł, /mcp pozwala uwierzytelnić się ponownie bez usuwania i ponownego dodawania serwera.

Codex

# Rozpocznij logowanie OAuth dla serwera streamable HTTP, który je wspiera
codex mcp login github

# Wyczyść zapisane poświadczenia, jeśli token jest błędny lub nieaktualny
codex mcp logout github

Dla serwerów opartych na tokenach ustaw zmienną przez tabelę env serwera w config.toml albo użyj bearer_token_env_var na serwerze z url, żeby token był wczytywany ze środowiska, a nie commitowany.

Notatka

“Permission denied” prawie zawsze oznacza, że token jest prawidłowy, ale ma za wąski zakres — na przykład token GitHuba bez dostępu repo. Zobacz przewodnik MCP Security po minimalne zakresy, jakich potrzebuje każdy serwer.

Poprawki specyficzne dla platformy

macOS Gatekeeper

# macOS poddaje kwarantannie pobrane binarki; wyczyść flagę, jeśli serwer jest zablokowany
xattr -d com.apple.quarantine /path/to/mcp/server

# Sprawdź, czy port lokalnego serwera nie jest już zajęty
lsof -i :3845

Polityka wykonywania Windows

# Zezwól na uruchamianie lokalnie utworzonych skryptów (per-user, bez uprawnień admina)
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

PATH i uprawnienia Linux

# Nigdy nie instaluj globalnych pakietów npm przez sudo — zamiast tego napraw prefix
mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
source ~/.bashrc

# Używaj menedżera wersji i aktywnego LTS (Node 18 jest EOL)
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.3/install.sh | bash
nvm install 22
nvm use 22

Problemy z siecią, firewallem i proxy

Serwery zdalne i lokalne z transportem HTTP dodają warstwę sieciową, której serwery stdio nie mają.

Localhost

# Potwierdź, że lokalny serwer faktycznie nasłuchuje na swoim porcie
curl http://127.0.0.1:3845/mcp

# Jeśli 127.0.0.1 jest zablokowany, ale serwer binduje 0.0.0.0, celuj w tego hosta:
# "url": "http://0.0.0.0:3845/mcp"

Firewall

# Linux (ufw)
sudo ufw allow 3845/tcp

# Windows Defender
netsh advfirewall firewall add rule name="MCP Server" dir=in action=allow protocol=TCP localport=3845

Corporate Proxy

Dla serwerów stdio za firmowym proxy przekaż proxy przez env serwera:

{
  "mcpServers": {
    "server": {
      "command": "npx",
      "args": ["-y", "@scope/server"],
      "env": {
        "HTTPS_PROXY": "http://proxy.company.com:8080",
        "NO_PROXY": "localhost,127.0.0.1"
      }
    }
  }
}

Wskazówka

Prompt do skopiowania — zdalny MCP, który nie chce się połączyć:

“My remote MCP server at http://127.0.0.1:3845/mcp will not connect. Run curl against that URL and report the HTTP status or connection error. Then check whether anything is already listening on port 3845 with lsof -i :3845, and tell me whether the problem is the server not running, the port being taken, or a firewall blocking localhost.”

Czytanie logów

Gdy własny raport agenta nie wystarcza, sięgnij wprost do logów:

Cursor

Otwórz panel Output (Cmd/Ctrl+Shift+U) i wybierz MCP Logs z listy rozwijanej. Szukaj prób połączenia, niepowodzeń uwierzytelniania i błędów rejestracji narzędzi.

Claude Code

# Strumieniuj wyjście debug specyficzne dla MCP
claude --debug "mcp"

Codex

# Codex zapisuje tutaj log sesji; podejrzyj go po odtworzeniu awarii
tail -n 100 ~/.codex/log/codex-tui.log

Gdy coś się zepsuje

Działa w Twoim terminalu, ale klient nadal pada. Klient używa innego PATH albo nieaktualnego cache. Wpisz na sztywno ścieżkę bezwzględną do npx/node w konfiguracji i uruchom npx clear-npx-cache.

Serwer się łączy, ale ładuje zero narzędzi. Padł podczas inicjalizacji — zwykle brakująca zmienna env. Uruchom komendę startową bezpośrednio i przeczytaj stderr; tam jest prawdziwy komunikat.

U Ciebie działa, a u kolegi z zespołu nie. Niemal na pewno masz zmienną env albo globalnie zainstalowaną zależność, których on nie ma. Przypnij wersję serwera w args i udokumentuj każdą wymaganą zmienną środowiskową w przewodniku kontrybuowania projektu.

Zdalny serwer działał wczoraj, a dziś zwraca 401. Token OAuth wygasł. Uruchom ponownie przepływ w przeglądarce: /mcp w Claude Code, codex mcp login <name> w Codeksie albo połącz ponownie z ustawień MCP w Cursorze.

Zawieszone lub osierocone procesy serwera. Znajdź je i zabij, a potem pozwól klientowi je odrodzić:

# macOS / Linux
pkill -f "mcp"

# Windows
tasklist | findstr "node"
taskkill /F /PID <pid>

Co dalej

MCP Best Practices Keep servers fast and context-efficient once they connect reliably.

MCP Security Scope tokens correctly so 'permission denied' stops happening.

Po pytania na poziomie protokołu specyfikacja i jej forum dyskusyjne żyją pod github.com/modelcontextprotocol oraz MCP GitHub Discussions. Po pomoc specyficzną dla narzędzi użyj Cursor Community Forum i Anthropic Discord.