MCP server not connecting? A runbook from URL to tool call

When an MCP server does not work, the client usually tells you very little: a red dot, "failed", or tools that never appear. The fix is to stop guessing and test each layer in order, from the network up to a real tool call. Each step below either passes, and you move on, or tells you exactly which layer is broken. The examples use a remote Streamable HTTP server at https://fetchmcp.net/mcp with a bearer key in LIVE_WEB_DATA_API_KEY.

1. Can you reach the URL?

Start below MCP. Send one request with curl and read the status line:

curl -si -X POST https://fetchmcp.net/mcp \
  -H "Authorization: Bearer $LIVE_WEB_DATA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | head -n 20

Read the result:

• No answer, DNS error or TLS error: a network problem (VPN, proxy, firewall, typo in the host). No client config will fix it.
• 404: wrong path. Many servers live at /mcp; SSE-era servers often used /sse.
• 401 / 403: the key is missing, wrong or not allowed. See the authentication guide.
• Any JSON-RPC answer, even an error about initialization: the server is reachable and your key works. Move on.

2. Does MCP Inspector see the tools?

MCP Inspector is the MCP project's own test client. Its CLI mode runs one method and prints the result, which takes the client out of the equation:

npx -y @modelcontextprotocol/inspector --cli https://fetchmcp.net/mcp \
  --transport http --method tools/list \
  --header "Authorization: Bearer $LIVE_WEB_DATA_API_KEY"

You can call a tool the same way with --method tools/call --tool-name get_account_status. Without --cli, Inspector opens a web UI where you can connect, browse tools and run calls by hand.

If Inspector lists the tools, the server and the key are fine. Whatever is still broken lives in the client config. If Inspector fails with the same URL and header, the problem is on the server side or in the key.

3. What does the client say?

Each client has one place that shows the status:

• Claude Code: claude mcp list checks every server and prints ✓ Connected or ✗ Failed to connect. claude mcp get live-web-data shows the stored entry, including scope, URL and headers. Inside a session, /mcp shows status and tools.
• Cursor: the MCP section of Cursor settings shows each server with a status dot and its tools. Toggling a server off and on reloads it.
• VS Code: the MCP servers list and the code lens above each entry in .vscode/mcp.json show the state, with commands to start, stop and show output.
• Claude Desktop: the tools menu in the chat input shows connected servers; errors appear as a banner after start.

4. Read the log

The real error is almost always written down:

• Claude Desktop: ~/Library/Logs/Claude/ on macOS, %APPDATA%\Claude\logs\ on Windows, with one mcp-server-<name>.log per server.
• Claude Code: start it with claude --debug to print MCP connection details.
• VS Code: "Show Output" for the server opens its output channel.
• Cursor: the Output panel has an MCP channel.

Search the log for the server name, then for error, 401, ENOENT or spawn.

Common failures by client

5. Make one cheap call

Once the client shows the server as connected, ask the agent to call the cheapest tool. On Live Web Data API's server that is get_account_status, which returns your plan, credits and rate limit and costs nothing. Then fetch https://example.com with a small cap. If both work, the connection is done; anything after this point is about result size or the pages themselves.

A runbook template for your team

Keep this next to your shared MCP config:

MCP runbook: live-web-data (fetch)
URL: https://fetchmcp.net/mcp        Transport: Streamable HTTP
Key: env LIVE_WEB_DATA_API_KEY (never in the repo)
1. curl tools/list with the header -> expect JSON-RPC answer
2. inspector --cli tools/list      -> expect get_page_contents
3. claude mcp list                 -> expect Connected
4. logs: ~/Library/Logs/Claude, claude --debug, VS Code output
5. call get_account_status, then fetch example.com
Owner: platform team. Last checked: YYYY-MM-DD

Update the "last checked" date whenever you re-run it after a client update. Live Web Data API's current client configs, which this runbook assumes, are in the MCP docs.