
You added an MCP server, restarted, and got nothing. The server isn't in the list, or it's there marked failed, or it connected and brought no tools with it. An MCP server not connecting is rarely one mysterious bug. It's usually one of a short list of causes, and which list depends on the kind of server you added.
This guide sorts the fixes by symptom, then by client: Claude Desktop, Claude on the web, Claude Code, Cursor, and ChatGPT. Every step comes from that client's own documentation, with the exact menu names and commands. At the end there's a way to skip most of the local failures altogether.
First, is your server local or remote?
Work out which kind of server you added before you fix anything, because the two fail in different ways. MCP (Model Context Protocol) is the standard way an AI client talks to outside tools, and an MCP server is the thing on the other end.
A local server is a program your client starts on your own machine and talks to over stdio, plain standard input and output. You add it as a command with args in a config file, and in Claude Desktop that file is claude_desktop_config.json. A remote server is a URL. In Claude you add it in the app as a custom connector, and Claude's docs set those up in your account, not in the config file.
| Symptom | Likely cause | Where to look |
|---|---|---|
| Local server missing in Claude Desktop | JSON error, relative path, missing Node, or no full restart | Claude Desktop |
| No Add custom connector option on a work plan | Only an Owner can add one | Claude on the web |
| Custom connector fails to connect | Server not public, wrong transport, or sign-in settings | Claude on the web |
| Claude Code says failed, pending, or needs authentication | The status label names the cause | Claude Code |
| Server never appears in Cursor's chat | Disabled in Customize, or not reloaded | Cursor |
| No way to add a full MCP server in ChatGPT | Your plan (full MCP is Business and Enterprise/Edu, Pro is read and fetch) or your workspace admin | ChatGPT |
| Connected, but tools are missing | Tools set to Blocked, or a stale tool list | Claude on the web, ChatGPT |
That split also decides where the traffic comes from. Claude reaches a remote server from Anthropic's cloud, not from your laptop, so the server has to be reachable on the public internet from Anthropic's IP ranges. Local servers stay on your machine, which is why they don't show up in claude.ai.
So if you pasted a URL into claude_desktop_config.json and it never appeared, the file isn't ignoring you. It's the file for the other kind of server.
A rough guide: a server that is missing usually points to local config; a URL that fails usually points to sign-in, your plan, or your admin.
Claude Desktop: local server not showing
A local server that won't appear in Claude Desktop is almost always a config, path, or restart problem. Before you edit anything, run the server's command by hand in a terminal, the way the MCP docs do with npx -y @modelcontextprotocol/server-filesystem /Users/username/Desktop /Users/username/Downloads. If it crashes there, it was always going to crash in Claude, and the terminal tells you why.
If it runs fine by hand, work through the config. As of November 2026, this order comes from the MCP project's guide to connecting local servers and its debugging page.
- Open the right file. Open the Claude menu, then Settings..., the Developer tab, and Edit Config. The file lives at
~/Library/Application Support/Claude/claude_desktop_config.jsonon macOS,%APPDATA%\Claude\claude_desktop_config.jsonon Windows, and~/.config/Claude/claude_desktop_config.jsonon Linux. - Check the JSON syntax. If your editor doesn't flag errors, paste the file into any JSON validator.
- Make every path absolute. A server that Claude starts may have an undefined working directory (like
/on macOS), so a relative path points nowhere useful. - Pass the variables it needs. Local servers inherit only a limited set of environment variables, so add an
envblock to the server's entry for API keys and the like. - Check that Node.js is installed. Many servers need it, including the Filesystem server, and
node --versiontells you whether it's there. - Quit Claude completely and reopen it.
Closing the window and reopening it feels like a restart. Claude Desktop disagrees.
Windows needs a little extra care. If the log shows an ENOENT error with ${APPDATA} in the path, add the expanded APPDATA value to the server's env. If npx fails, check that %APPDATA%\npm exists, and run npm install -g npm if it doesn't.
Once it works, the server shows up under the plus icon in the chat box, Add files, connectors, and more, then Connectors.
Read the logs
Claude Desktop keeps separate MCP logs, and they answer different questions. mcp.log records connections and connection failures; mcp-server-SERVERNAME.log holds that one server's stderr output. You'll find them in ~/Library/Logs/Claude on macOS, %APPDATA%\Claude\logs on Windows, or ~/.config/Claude/logs on Linux.
The MCP docs give a command for macOS and Linux that follows the last 20 lines while you restart.
# macOS
tail -n 20 -f ~/Library/Logs/Claude/mcp*.log
# Linux
tail -n 20 -f ~/.config/Claude/logs/mcp*.logIf you wrote the server yourself, send your debug output to stderr, since that's what lands in the server's log.
For a closer look, Claude Desktop also has DevTools. Create a developer_settings.json file containing {"allowDevTools": true}, then press Command-Option-I on macOS or Ctrl+Alt+I on Windows.
Claude on the web and Desktop: custom connector fails or has no tools
Remote servers in Claude are custom connectors, added by URL in your account, and the same rules apply on the web and in Desktop. As of November 2026, Claude's docs give this path for Free, Pro, Max, and Ultra, starting at Customize > Connectors; the dialog layout can vary by organization, so your labels may sit in slightly different places.
- Open Customize > Connectors, choose Add, then Add custom connector.
- Enter a name and the server URL, then choose Continue.
- Pick the authentication settings and choose Add.
- Choose Connect if it appears, and finish the sign-in.
Your plan sets the first limit. Custom connectors by URL work on Free, Pro, Max, Ultra, Team, and Enterprise, but Free allows one custom connector. If you already have one on Free, the next one won't fit.
On Team and Enterprise, an Owner adds the connector first, under Organization settings > Connectors > Add > Custom (choose Web if asked). Members then find it under Customize > Connectors with a Custom label and choose Connect. On Enterprise, a member with a custom role that manages the organization's libraries can add one too; everyone else has to ask an Owner.
If Add custom connector is missing from your menu, you haven't lost the button. You're a member, and the button belongs to your Owner. On a work plan, message your Owner before you debug anything else.
Next, check that Claude can reach the server. It has to be on public HTTPS and reachable from Anthropic's IP ranges, so a server behind a VPN, firewall, or private network needs those ranges allowlisted, and that includes connectors you use from Desktop. Anthropic's custom connector article links to the list.
Then check the URL itself. It's the HTTPS address where the server accepts MCP requests, such as https://mcp.example.com/mcp. A URL ending in /sse selects the older SSE transport, so change Advanced > Transport only if the server's docs tell you to.
Sign-in is the last usual suspect, and it's two choices. First you pick when people sign in: Sign in now, Sign in when needed, or No sign-in. Then you pick an OAuth client, the identity your connector uses in the standard "sign in with your account" flow: Claude's published identity, automatic registration, or your own. Claude's docs recommend the published identity, so pick that unless the server's docs say otherwise. Choose carefully, because you can't edit these settings later. A change means removing the connector and adding it again, and members then reconnect.
Request headers are open only to a limited set of organizations, with up to four headers. The value goes out exactly as you type it, so write Bearer your-token in full; on an OAuth connection you can't set Authorization as a header at all.
Connected, but no tools? Check the switches. In a chat, choose +, then Connectors, and make sure this connector is on for that chat. Then open the connector under Customize > Connectors and check that no tool is set to Blocked. Our Claude setup page walks through the same screens with one specific URL.
Claude Code: /mcp says failed, pending or needs authentication
Claude Code runs both kinds of server from the terminal, and it shows a status label for each server that names the cause. Start with claude mcp list, which shows each server's health, and /mcp inside a session, which shows status and lets you sign in. As of November 2026, these labels and fixes come from Anthropic's Claude Code MCP docs.
| Status label | What it means | Fix |
|---|---|---|
| Connected | It works | Nothing to do |
| Needs authentication | Sign-in missing or expired | Run /mcp, pick the server, sign in again |
| Failed to connect | The server didn't start or didn't answer | Inspect it with claude mcp get <name>, then run /mcp reconnect all (v2.1.284+) |
| Pending approval | A project server you haven't approved | Run claude and approve it |
| Rejected | You declined it earlier | See disabledMcpjsonServers in settings, or run claude mcp reset-project-choices |
| Disabled for this project | Switched off here | Re-enable it in /mcp |
| Blocked by enterprise managed policy | Your organization's policy | Ask whoever manages Claude Code for you |
Not every label shows everywhere: Rejected appears in claude mcp get <name>, not in /mcp or claude mcp list, so check there if a project server seems to have vanished.
An expired sign-in reads MCP server "<name>" needs you to sign in again (run /mcp to re-authenticate), which is refreshingly direct for an error message.
When a server doesn't appear at all, check these first:
- Wrong scope or folder. The default scope is local: stored in
~/.claude.jsonand loaded only in the project where you added it. User scope lives in the same file but loads in every project, and project scope goes in.mcp.jsonat the project root. - A duplicate won. Among the servers you configure, precedence runs Local, Project, User, Plugin, then claude.ai connectors, and the winning entry is used whole, with no merging of fields. A plugin or connector pointing at the same URL or command counts as a duplicate.
- A reserved name.
workspace,claude-in-chrome,computer-use,Claude Preview, andClaude Browserare taken, so rename yours. - An unset variable. An unset
${VAR}in.mcp.jsontriggers a warning and stays in place as literal text;${VAR:-default}supplies a fallback.
The server you added in one repo that "vanished" in another didn't go anywhere. It's still in the first repo, waiting for you. Add personal servers with --scope user so they follow you between projects.
The docs add a remote server with a URL and a local one with a command after --, which separates Claude's options from the server's own command.
# Remote server over HTTP
claude mcp add --transport http my-server https://mcp.example.com/mcp
# Local server over stdio
claude mcp add --env API_KEY=your-key --transport stdio my-server -- npx -y some-packageSSE is deprecated in Claude Code. Version 2.1.265 and later tries HTTP first and switches to SSE if HTTP isn't accepted; earlier versions need --transport sse.
A few more fixes cover slow starts, big outputs, and sign-in edge cases:
- Slow to start.
MCP_TIMEOUT=10000 claudegives a local server 10 seconds to start. - Huge results. Claude Code warns when a tool's output passes 10,000 tokens and caps it with
MAX_MCP_OUTPUT_TOKENS, which defaults to 25,000. - A full trace.
claude --debug-file <path>writes a debug log you can read afterwards. - The browser can't hand the sign-in back. Open the URL Claude Code shows, sign in, and paste the code at the
Paste code here >prompt. - Start sign-in over. Clear authentication in the
/mcpmenu revokes what's stored. - No Dynamic Client Registration. That's the feature that lets a server register Claude Code as a sign-in client on its own. Without it, pass
--client-id,--client-secret, and--callback-portwhen you add the server, and useMCP_CLIENT_SECRETin CI. This one matters mostly if you run the server yourself.
Remote and local servers also recover differently. A dropped remote server is retried up to five times, waiting longer each time from one second, but stdio servers aren't retried automatically. In an interactive session, a crashed local server stays down until you reconnect it in /mcp.
A big tool list is not a failure in itself. Tool search is on by default, there's no fixed per-server tool cap, and the practical limit is your context window; ENABLE_TOOL_SEARCH=false turns tool search off.
If a server you never added shows up in /mcp, it probably came from your claude.ai account, since those connectors appear in Claude Code too. For cloud sessions, reauthorize one at claude.ai/customize/connectors. To hide them, start with ENABLE_CLAUDEAI_MCP_SERVERS=false claude, or toggle them per project in /mcp.
Cursor: MCP server not working
Cursor keeps its servers in JSON files, like Claude Desktop, but its logs and switches live inside the editor. As of November 2026, Cursor supports stdio, SSE, and Streamable HTTP transports. It reads servers from .cursor/mcp.json in a project or ~/.cursor/mcp.json globally, under a top-level mcpServers key.
A local entry needs type set to "stdio" and a command, plus args, env, and envFile as needed; a remote entry uses url and headers. Variables such as ${env:NAME}, ${userHome}, and ${workspaceFolder} work in the command, args, env, url, and headers.
{
"mcpServers": {
"local-tool": {
"type": "stdio",
"command": "npx",
"args": ["-y", "some-package"],
"env": { "API_KEY": "${env:MY_API_KEY}" }
},
"remote-tool": {
"url": "https://mcp.example.com/mcp"
}
}
}Check the logs before you touch the JSON. Open the Output panel with Cmd+Shift+U and pick "MCP Logs" from the dropdown.
Then check the switch. Servers are turned on and off from Customize in the sidebar, and a disabled server won't load or appear in chat. From inside a chat, a disabled server looks exactly like one you never configured.
If you changed a custom server's local files, restart Cursor.
Sign-in uses OAuth's authorization code flow with PKCE: the usual browser sign-in, plus a check that stops someone who intercepts the code from redeeming it. Refresh tokens renew expired access, and without one you sign in again. If you run the server's OAuth app yourself, register Cursor's redirect URLs, the addresses your sign-in page sends people back to: http://localhost:8787/callback for the desktop app, and https://www.cursor.com/agents/mcp/oauth/callback for the web and Cursor Agents.
Cursor says it isolates server failures, so one crash shouldn't take the others down. If every server fails at once, suspect the shared config file before any single server.
Cursor's MCP page doesn't document a tool-count cap or per-tool switches for users. Our Cursor setup page shows a remote entry end to end.
ChatGPT: custom MCP server or connector won't connect
In ChatGPT, a custom MCP server becomes a plugin you create on the web, and your plan decides how much it can do. As of November 2026, OpenAI's developer mode and MCP apps article gives this path, and Developer Mode isn't required.
- Open Plugins, choose the plus button, then Add custom MCP server.
- Give it a name.
- Under Connection, enter the public HTTPS URL, or choose Tunnel for a Secure MCP Tunnel.
- Set up authentication.
- Accept the risk warning with I understand and want to continue.
- Choose Create as a plugin.
Per OpenAI, full MCP with write access is for Business and Enterprise/Edu, on the web and not on mobile. Pro can connect custom MCP servers as well, but with read and fetch permissions only. For any other plan, check OpenAI's page before assuming it works. If you're on Business or Enterprise/Edu and still can't add a server, the fix is your admin, not your server.
Workspaces add that admin gate. On Business, only admins and owners create and publish, and the permission is Create plugins with MCPs in workspace settings. On Enterprise/Edu, admins and owners create and test, role-based access can let selected members create, and only admins and owners publish for the workspace.
Older and third-party guides describe a Developer Mode path under Settings > Apps & Connectors > Create, with different plan rules. OpenAI's article documents the Plugins flow above, so follow that. Hunting through Settings for a menu your screen doesn't show is a fine way to lose an afternoon.
Your local server won't connect directly. ChatGPT reaches local servers only through a Secure MCP Tunnel.
On a workspace with admin-approved servers, stale or missing tools come from publishing. An approved server is a frozen snapshot, and a developer's changes don't apply until an admin publishes an update. After a change that isn't backward compatible, admins refresh tool actions from workspace settings, and users aren't prompted. On Enterprise/Edu that's Workspace settings > Apps > ••• > Action control, where new actions start disabled.
If people get asked to sign in again once their first authorization expires, look at the server's OAuth provider. It has to issue refresh tokens, the long-lived tokens that renew access without a new sign-in. Whoever runs the server should include offline_access and list it in scopes_supported, then recreate the app so ChatGPT fetches the updated metadata.
If you're building the server, OpenAI's Apps SDK convention is a streamable HTTP endpoint, typically at /mcp. Our ChatGPT setup page covers the plugin screens for one remote URL.
Still failing? Test the server outside the client
Take the client out of the picture and test the server on its own. The MCP debugging docs give three checks for connection problems: read the client's logs, confirm the server process is running, and test the server standalone with the MCP Inspector, the MCP project's own test client.
Remote servers need one more step. A Streamable HTTP server's stderr isn't captured by the client, so read the server's own logs and test the endpoint with curl or your browser's DevTools Network panel.
If it fails in the Inspector too, the client was innocent all along.
Skip the local failures: one remote URL in every client
Look back at the Claude Desktop and Cursor fixes: config JSON, absolute paths, Node and npx, missing environment variables, full restarts. Most of them come from running a program on your own machine. A remote URL has nothing to install and no command to run, so Node, npx, command paths, and environment variables drop out. Cursor still reads its remote entry from mcp.json, so a stray comma can still bite, but that is one line to check, not a program to keep alive.
What a remote URL doesn't remove is each client's own rules. Claude Free still allows one custom connector, a Team or Enterprise Owner still adds connectors first, and ChatGPT's full MCP is still for Business and Enterprise/Edu. No server, ours included, can change those.
Arc0 publishes this blog, so take this part as the worked example we know best. Arc0 MCP is one endpoint, https://api.arc0.ai/mcp, bound to you: interactive clients sign in with OAuth, and others use an API key. It speaks Streamable HTTP (MCP's transport for remote servers) and is stateless, so each request stands on its own; its latest supported protocol version is 2025-11-25. The same URL works in Claude, ChatGPT, Cursor, Claude Code, Codex, VS Code, and any other remote-MCP client.
In Claude Code it's one line, at user scope so it follows you between projects.
claude mcp add --transport http --scope user arc0 https://api.arc0.ai/mcpIn Cursor it's a single url entry.
{
"mcpServers": {
"arc0": { "url": "https://api.arc0.ai/mcp" }
}
}Behind that one URL sit hundreds of apps, from a catalog of 1,484. Every client uses the same Arc0 account, so you connect each app once there, not once per client. The agent doesn't load every tool from every app either: it searches a short list of what you've authorized with meta tools such as search_actions and execute_action. Calls run on Arc0's servers, and your credentials never reach the agent or the model.
The plain limit: Arc0 can't lift a plan or admin gate. It is one connector, though, so on Claude Free it fits the one-connector limit with the catalog behind it.
If you use more than one client, debug one URL, not a server per client. The Personal plan is free, with one MCP URL, scopes per assistant, a 7-day audit log, and token export. Get your URL from Arc0 for individuals, connect one app, and add it to your client with the MCP client setup pages.
For the details, the MCP client docs cover each client and the Arc0 MCP docs cover the endpoint itself.