MCP Server Not Working? Common Errors and Fixes
Updated November 5, 2026
Short answer: Start with the error code. A 401 usually means you need to sign in. A 404 or 405 usually means the URL is wrong. A 406 means the client sent the wrong headers. A 500 is a problem on the server. For local servers, the usual causes are a missing runtime, invalid JSON or output printed to stdout.
We test every hosted server in our directory each day, so we see these failures constantly. Right now 13 of our 456 hosted servers aren't responding.
What does each error mean?
| Error | Usually means | What to do |
|---|---|---|
| 401 | Sign-in required. This is normal for many servers. | Complete the sign-in, or add the API key as a header. In Claude Code, run /mcp. |
| 403 | You are signed in but not allowed. | Check your plan, scopes and any IP allow list. |
| 404 | Wrong path. | Check the docs. Common paths are /mcp, /api/mcp and /sse. |
| 405 | The URL exists but doesn't accept MCP requests. It is often a web page at that address. | Find the real endpoint in the docs. We've seen a human-readable page at /mcp with the real server elsewhere. |
| 406 | The client didn't send the headers the server wants. | Send Accept: application/json, text/event-stream. Most apps do this for you, so it mainly affects custom clients. |
| 429 | Rate limited. | Wait and retry, or check your plan's limits. |
| 500 | The server crashed or has a bug. | Try again later. Some servers return 500 instead of 401 when you aren't signed in, so try signing in too. |
| Timeout | The server is slow or asleep. | Retry. Free hosting often sleeps until the first request arrives. |
The server connects but no tools appear
- Finish the sign-in. Many servers hide their tools until you do.
- Restart your app, or reload its MCP list. In Claude Code, run
/mcp. - Turn it on for the conversation. In Claude, click + and select Connectors. In ChatGPT, type @.
- Run
claude mcp listto see each server's health.
A local server won't start
- Runtime missing: check that
node,npx,uvxordockerworks in a terminal. Desktop apps may not see the same PATH as your terminal, so try the full path to the command. - Invalid JSON: a stray comma breaks the whole file. Paste it into a JSON checker.
- Wrong key: VS Code's
.vscode/mcp.jsonusesservers, while most others usemcpServers. - Run it by hand: paste the start command into a terminal to see the real error.
- Printing to stdout (for developers): a stdio server must use stdout only for protocol messages. Send logs to stderr.
How can I test a server myself?
Send a real initialize request. A healthy server returns JSON or an event stream, and a server that needs sign-in returns 401 with a WWW-Authenticate header.
curl -i -X POST https://example.com/mcp \
-H 'Content-Type: application/json' \
-H 'Accept: application/json, text/event-stream' \
-d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{},"clientInfo":{"name":"test","version":"1"}}}'Our security and testing picks also include servers that check other servers for you.
Frequently asked questions
Why does my MCP server say 401 Unauthorized?
It usually just means you need to sign in or provide an API key. A 401 with a WWW-Authenticate header is how a server asks a client to start signing in.
Why does my MCP server return 405 Method Not Allowed?
MCP clients send POST requests. A 405 usually means the URL isn't the MCP endpoint, often because it is a normal web page.
Why are my MCP tools not showing up?
The most common reasons are an unfinished sign-in, an app that needs a restart, or a connector that is not enabled for the conversation.