MCP server not connecting? Fix 401, 404, 405 and missing tools
A quick fix list for MCP connection problems in Claude, Claude Code, Codex, VS Code and Cursor: what each error means and the one thing to do about it.
In this post
- Check the address first
- What each error means
- Fixes for each client
- When a tool doesn't show up
Most MCP connection problems come down to a handful of causes: a wrong address, a sign-in that didn't finish, or a config file in the wrong shape. Find what you see below and do the one thing next to it.
First, check the address#
Every project has one address. Copy it from the console's Connect screen, or run gxmesh connect in the project folder:
https://<org>.mcp.glxymesh.com/<project>
- Use your organization's slug, not its display name.
- Don't add
/mcpto the end. Only the localgxmesh devserver uses/mcp. - There's no API key. The client signs in through your browser.
What each error means#
| What you see | What to do |
|---|---|
404 | The org or project doesn't exist for you. A project you aren't a member of looks the same as one that doesn't exist. Check the address on Connect. |
401 after it worked before | The sign-in expired. Sign in again in the client. It won't register again. |
405 | Normal when you open the address in a browser. The server only accepts POST. Try it in your client. |
| No sign-in page opens | The client hasn't tried to connect yet. Start the server or choose Authenticate (see below). |
| "This project is waking up…" | The project's tools were asleep after a week without calls. Try again in a few seconds. |
Fixes for each client#
| Client | Common fix |
|---|---|
| VS Code | .vscode/mcp.json must use servers, not mcpServers. Then choose Start above the entry. |
| Claude Code | Run /mcp inside the session and choose your server, then Authenticate. |
| Codex | Run codex mcp login <name>, then restart the session and check /mcp. |
| Cursor | Add no auth block. Open MCP settings, select the server and sign in. Check its switch is on. |
| Windsurf | The address key is serverUrl, not url. |
| Claude | Add it under Customize → Connectors, leave OAuth settings alone, then switch it on in the chat's + menu. |
A tool doesn't show up#
- Run
gxmesh revisionsto check your latest push went live, in the project you connected to. - In VS Code, open Configure Tools and make sure the tools are ticked.
- Restart the client session. Many clients read the tool list only when they start.
- Is the tool you see out of date? Some clients cache the list. Reconnect the server.
How sign-in works, in short#
The first call has no token, so the server answers 401 and points to accounts.glxymesh.com. The client registers itself, your browser opens, you approve, and the client gets a token that belongs to you. Everyone signs in with their own account and must be a member of the organization. Remove someone and it takes effect on their next call.
Step-by-step setup for every client is in Connect MCP servers to AI clients and the connect guide.
Explore MCP guides by task: creation, hosting, connections and security.
