MCP (Model Context Protocol) is the standard that lets an agent like Claude Code talk to external tools and data through small server processes. When it works, your server shows up and its tools become available. When it does not, you usually see one of three symptoms: the server never appears in the tool list, it appears but shows a failed or disconnected state, or the agent reports that the server failed to start.
Common causes
Invalid config JSON
A trailing comma, a missing quote, or a stray bracket makes the whole config unreadable, so no servers load at all.
Wrong or non-executable command
The command or path in the config points to something that is not on PATH, not installed, or not runnable in the agent's environment.
Missing args or env vars
The server needs an argument (a folder, a URL) or an environment variable (an API key, a token) that was not set, so it starts and immediately exits.
No restart after editing config
Many agents read the MCP config only at startup. Edits made while the app is running are ignored until you fully restart it.
Transport mismatch
The config declares stdio but the server speaks SSE or HTTP, or the reverse. The two sides never complete a handshake.
Version or runtime mismatch
An outdated agent, an old server package, or a missing Node or Python runtime causes the process to fail before it connects.
Fix it step by step
- Validate the config JSONPaste your MCP config into any JSON validator or run it through a linter. Fix trailing commas, unbalanced brackets, and unescaped backslashes in Windows paths before anything else.
- Run the server standalone in a terminalCopy the exact command and args from your config and run them directly in a terminal. If it errors, is not found, or exits immediately, the problem is the server or its environment, not the agent.
- Check the command and pathConfirm the executable exists and is on PATH. For npx or uvx based servers, make sure Node or Python is installed. On Windows you may need the full path or the .cmd form of a launcher.
- Set required args and env varsProvide every argument the server expects and every environment variable it reads, especially API keys and tokens. A server that starts without its key often exits silently and looks like a connection failure.
- Match the transportMake sure the transport in your config matches what the server actually speaks. Local process servers usually use stdio; remote servers use SSE or HTTP with a URL. Do not mix them.
- Restart the agent fullyQuit the app completely and reopen it, or restart the CLI session, so it re-reads the config. A background process can keep the old config alive, so confirm the app has actually exited.
- Read the logsCheck the agent's MCP or developer logs for the exact error. Messages like command not found, permission denied, or non-zero exit tell you precisely which of the steps above to revisit.
{
"mcpServers": {
"filesystem": {
"command": "npx",
"args": [
"-y",
"@modelcontextprotocol/server-filesystem",
"/path/to/allowed/directory"
]
},
"example-with-key": {
"command": "npx",
"args": ["-y", "some-mcp-server"],
"env": {
"API_KEY": "your-key-here"
}
}
}
}Skip the JSON wrangling
A lot of these failures come from hand editing JSON: a stray comma, a wrong path, a forgotten env var. Wuwei is a free, open-source coding agent that supports MCP servers with a built-in catalog for one-click install, plus custom config when you need it. The catalog fills in the command, args, and env fields for common servers, which removes the most common source of typos. You can still paste a manual config for anything not in the catalog.
FAQ
Why is my MCP server not showing up?
Usually the config JSON is invalid, so nothing loads, or the app was not restarted after the config was edited. Validate the JSON, then fully restart the agent so it re-reads the config.
How do I know if my MCP server is running?
Run the exact command and args from your config directly in a terminal. If it starts and waits without exiting or erroring, the server itself is fine and the issue is in the config or the agent. If it fails there, fix the server or its environment first.
Why does Claude say the MCP server failed?
A failed state usually means the process started and then exited, most often because a required argument or environment variable like an API key was missing, the command was not found, or the transport did not match. Check the logs for the exact exit reason.
Do I need to restart after adding an MCP server?
Yes, in most agents. The MCP config is read at startup, so a new or edited server will not appear until you fully quit and reopen the app or restart the CLI session.