AgentHubAgentHub

Guides·MCP

Fix MCP connection failures

MCP server not connecting, empty tool list, or tool errors? A four-step debug flow—status, startup logs, env vars, remote transports—for Cursor, Claude Code, and VS Code.

What connected looks like

Set a baseline first—three signals, all required:

  1. The server shows Connected in client MCP settings (green / Tools > 0)
  2. Chat triggers visible tool calls (list_directory, fetch, …)
  3. Replies contain real data, not invented content

Cheapest smoke test: ask it to "list files in the current directory." If that passes, only app-level params remain.

Step 1: read the startup log

A server that exits instantly is a config/env problem, and the log names it:

  • Cursor: Settings → MCP → View log
  • Claude Code: run claude --debug or check ~/.claude/logs/
  • VS Code: Output panel → MCP channel

Common errors:

ErrorCauseFix
command not found: npx / uvxNot on PATHUse an absolute path (GUI apps skip shell rc files)
Cannot find moduleTypo / renamed packageCopy the exact command from the AgentHub resource page
econnrefused / slow downloadsNetwork or registrySet npm/pypi mirrors, or pick a remote-hosted server
port is already allocatedPort busyChange the port or kill the old process

Step 2: JSON and env vars

  • JSON syntax: matching commas/quotes/braces; watch for smart quotes introduced by copy-paste
  • Split args: each flag is its own array item — "args": ["-y", "pkg"], not "-y pkg"
  • Env vars: keys and connection strings belong in env; trim spaces; replace placeholder values
  • No comments: mcp.json is strict JSON in most clients—strip comments while debugging
  • Reload the window or client after edits; hot reload is rare

Step 3: remote (HTTP / SSE) servers

Remote MCPs (streamable-http / SSE) spawn no local process, so debug differently:

  1. Reachability: curl -i <endpoint> first; 401/403 usually means a missing/expired key
  2. Auth shape: header name and Authorization format must match provider docs exactly
  3. Protocol version: older clients may speak only SSE—switch transport to test
  4. Proxy policy: on corporate networks check domain allow-lists and TLS interception

Behind restrictive networks, prefer a China-hosted twin of the same capability listed on AgentHub.

Connected but wrong results?

  • Empty tool list: server runs but registers nothing—check you picked the right distribution of the package
  • Permission denied: token scopes too narrow; re-read the provider's permission docs and re-authorize
  • Answers look invented: the model skipped the tool—require it explicitly; or the call failed silently, re-check logs
  • Still stuck: search the upstream repo's Issues linked from the AgentHub resource page, and include log snippets
Fix MCP connection failures — Install Guide for - AgentHub