MCP Not Working? 15 Fixes (MCP Troubleshooting Guide 2026)

TL;DR: Most MCP failures are one of four things: the config lives in a file your client never reads, the JSON is malformed, the client was not fully restarted, or the token is wrong for the auth method. Check your client's log file first, then work down the 15 fixes below.

Why is my MCP server not working?

Nine times out of ten the server is fine. What breaks is the handoff: a config file the client never reads, a credential in the wrong header, or a transport it does not speak. Each client fails differently and logs elsewhere.

Work in this order.

1. Is the server listed at all? If not: config location or syntax.
2. Does it say connected? If not: auth, network, or transport.
3. Is the tool count above zero? If not: the handshake worked, discovery did not.
4. Only then: is the model actually calling the tools?

Wrong path is the most common failure, so start here.

Every path comes from the vendor's own docs, checked August 26, 2026. Sources are at the end.

Fixes 1 to 4: the config file itself

1. The config is in the wrong file for your client

Symptom: you saved the config, restarted, and the server does not appear anywhere. No error, no red dot, nothing.

Cause: MCP configs look almost identical across clients, so a snippet from a Cursor tutorial ends up in Claude Desktop's file, or the reverse. The client reads its own file, finds nothing, and reports exactly what it sees.

Fix: use the table above. For Claude Desktop the documented route is Settings, then Developer, then Edit Config, which creates the file if missing. One catch: claude_desktop_config.json is documented with command and args for local stdio servers. A remote server like ours belongs under Settings, then Connectors, then Add custom connector.

# Confirm the file your client actually reads exists and is non-empty
cat ~/Library/Application\ Support/Claude/claude_desktop_config.json   # Claude Desktop, macOS
cat ~/.cursor/mcp.json                                                 # Cursor, global
cat ./.mcp.json                                                        # Claude Code, project scope
cat ~/.codex/config.toml                                               # Codex CLI

2. The JSON or TOML is malformed

Symptom: the whole MCP section disappears, not just one server. Servers that worked yesterday are gone too.

Cause: JSON has no comments and no trailing commas, Windows paths need doubled backslashes, and copying from a rendered web page often brings smart quotes, which a parser does not accept as quotes.

Fix: validate before you restart. One bad character takes out every server in the file.

# JSON clients: a parse error prints here instead of failing silently later
python3 -m json.tool ~/.cursor/mcp.json > /dev/null && echo "valid JSON"

# Codex: TOML, not JSON. Different syntax, same failure mode.
python3 -c "import tomllib,sys;tomllib.load(open(sys.argv[1],'rb'));print('valid TOML')" ~/.codex/config.toml

The MCP debugging guide names invalid JSON syntax, missing required fields, and type mismatches as the three standard config errors.

3. You edited the config but never really restarted

Symptom: the change is definitely saved, and the client behaves as if it is not.

Cause: closing the window is not quitting the app. The MCP debugging guide is explicit: a config change means restarting the client, and for Claude Desktop that is a full quit and reopen.

Fix: quit properly, then reopen.

# macOS: fully quit Claude Desktop, then relaunch
osascript -e 'quit app "Claude"' && sleep 2 && open -a "Claude"

Claude Code and Codex read config at session start, so exit and start a new session. Cursor gives each server an on/off toggle in its MCP settings, faster than restarting the editor.

4. Two servers are fighting over the same name

Symptom: you configured a server, the client shows a server with that name, and it is the wrong one. Or a rename in one file quietly does nothing.

Cause: three things collide. A duplicate key in one JSON object means the last wins silently. Claude Code resolves a repeated name by scope precedence rather than merging, so local beats project beats user. And it reserves names for built-in servers, including workspace, claude-in-chrome, and computer-use; a config using one is skipped at load with a warning.

Fix: pick a distinctive key. We use pa, which also keeps slash commands short. Then check which definition won.

claude mcp list          # every configured server plus a health status
claude mcp get pa        # the winning definition, its scope, and any Issue line

Fixes 5 to 7: authentication

5. The OAuth flow never completes

Symptom: the browser opens, you approve, and the client still says the server needs authentication. Or it never opens at all.

Cause: three failure modes wear the same face. No local browser, as on SSH or Linux without a display server. A callback that cannot reach the client because the loopback port is blocked. Or a server requiring a pre-registered redirect URI, which fails as a redirect URI mismatch.

Fix: run the flow from the shell, where you can see it fail.

# Claude Code v2.1.186+: run a configured server's OAuth flow directly
claude mcp login pa

# No local browser? Print the URL, open it elsewhere, paste the callback back
claude mcp login pa --no-browser

# Codex CLI
codex mcp login pa

The documented recovery for a failed redirect is to paste the full callback URL from your browser's address bar into the prompt Claude Code shows. If the server needs a fixed port, --callback-port 8080 pins it to a registered http://localhost:8080/callback. Cursor uses fixed redirect URLs: https://www.cursor.com/agents/mcp/oauth/callback for web, http://localhost:8787/callback for desktop.

6. The token expired or was never scoped correctly

Symptom: it worked for a week, then every tool call started failing.

Cause: access tokens expire. Refresh usually happens invisibly, but when a server rejects the stored refresh token there is nothing left to refresh with.

Fix: re-authenticate rather than debug further. Claude Code documents this precisely: on a 401 Unauthorized for a server you already signed in to, it refreshes the token, reconnects, and retries once, flagging the server only if that retry fails too. When the refresh token itself is rejected it shows a notice pointing at /mcp, where Re-authenticate sits in the server's menu.

claude mcp logout pa && claude mcp login pa   # clear stored credentials, sign in fresh

7. You used a pa_live_ token where OAuth was expected

Symptom: the server reports failed, not "needs authentication", and no browser window ever opens.

Cause: the sharpest edge in the protocol. Claude Code documents it plainly: if you set headers.Authorization and the server rejects that header, the connection is reported as failed instead of falling back to OAuth. A bearer header suppresses the OAuth path, so a stale or truncated token never degrades into a sign-in prompt. It just looks broken.

Fix: decide which one you are using and configure only that.

# Interactive use: no header at all. Let OAuth run.
claude mcp add --transport http pa https://mcp.prompt-architects.com/mcp

# Headless or CI: bearer token, no OAuth
claude mcp add --transport http pa https://mcp.prompt-architects.com/mcp \
  --header "Authorization: Bearer pa_live_xxxxxxxxxxxx"

In Codex, keep the token out of the file and reference an environment variable:

[mcp_servers.pa]
url = "https://mcp.prompt-architects.com/mcp"
bearer_token_env_var = "PA_MCP_TOKEN"

Fixes 8 to 11: the network path

8. Transport mismatch

Symptom: an immediate connection error, or a connection that opens and closes straight away.

Cause: "MCP server" covers several wire protocols: Streamable HTTP, the older SSE, local stdio, and in Claude Code a WebSocket type. Configuring one against a server that speaks another fails at the handshake.

Fix: match the transport to the endpoint. Ours is Streamable HTTP.

claude mcp add --transport http pa  https://mcp.prompt-architects.com/mcp   # correct
claude mcp add --transport sse  pa  https://mcp.prompt-architects.com/mcp   # wrong for us

One naming quirk saves time: in .mcp.json, ~/.claude.json, and claude mcp add-json, Claude Code accepts streamable-http as an alias for http, so configs copied from other vendors' docs work unmodified. Cursor lists stdio, SSE, and Streamable HTTP. Codex treats a url entry as Streamable HTTP and a command entry as stdio.

9. A firewall or proxy is in the way

Symptom: it works on your laptop at home and fails on the office network. Or it works in Claude Code and fails in Claude.ai.

Cause: the two clients reach your server from different places. A local client connects from your machine. Anthropic's custom connector documentation states that remote MCP servers connect over the public internet from Anthropic's cloud infrastructure, so a server on a private network will not connect unless you allowlist Anthropic's IP addresses. TLS-inspecting corporate proxies cause a quieter version of the same problem: they break the long-lived streaming responses Streamable HTTP depends on.

Fix: test the endpoint from the same network, outside any MCP client.

# Reachability and TLS, with no MCP client involved
curl -sS -o /dev/null -w "%{http_code} %{time_total}s\n" \
  https://mcp.prompt-architects.com/mcp

# 000 means DNS or TLS failure. 401/403 means you reached us and need to sign in.

A 401 here is good news. It means the network path is clean and the problem is fix 5, 6, or 7.

10. The endpoint URL is wrong

Symptom: a 404, or a 405 Method Not Allowed, or a connection that never negotiates.

Cause: MCP endpoints are path-specific. Many servers expose /mcp for Streamable HTTP and a separate /sse for the legacy transport, and the bare domain is often a marketing page. A trailing slash, a missing path segment, or a URL wrapped across two lines by a docs site all fail the same way.

Fix: ours is exactly this:

https://mcp.prompt-architects.com/mcp

Retype it rather than copying from a PDF or a chat message. Claude Code flags whitespace in url as it does in headers, and reports an empty url as not configured rather than attempting a connection.

11. Version skew between client and server

Symptom: the server connects in one client and not another, or capabilities that exist stop appearing after an update.

Cause: client and server negotiate a protocol revision at connect time, and clients ship far more often than servers. Claude Code now runs two client runtimes: v1 on MCP TypeScript SDK 1.x, and v2 on SDK 2.0, which adds protocol revision 2026-07-28. On v2 it asks HTTP servers whether they support the newer revision. An UnsupportedProtocolVersionError (-32022) lists the server's supported versions in its data field, the fastest way to see a mismatch.

Fix: update the client first, then check the server.

claude update          # Claude Code
codex update           # Codex CLI
# Claude Desktop: the Claude menu, then Check for Updates

Local stdio servers add a second skew: Node version. The MCP Inspector requires Node 22.19.0 or newer, and many published servers assume a recent LTS.

Fixes 12 to 14: it connects, but nothing happens

12. The tools are there and the model never calls them

Symptom: the status panel says connected with four tools, and the model answers your question as if the server did not exist.

Cause: nothing is broken. A connected server offers tool use to the model; it does not compel it. The model weighs your phrasing against its instructions, and vague requests lose that argument.

Fix: stop asking and start invoking. MCP prompts surface as slash commands in the format /mcp__servername__promptname, so our tools become:

/mcp__pa__improve    clarify and structure this prompt
/mcp__pa__refine     ask clarifying questions first
/mcp__pa__shorten    compress while preserving intent
/mcp__pa__enhance    add structure and depth

A slash command removes model discretion. If it works and plain-English requests do not, the server is healthy and you have a prompting problem, not an MCP problem. Our guide to prompt engineering fundamentals covers that side.

13. It fails silently with no error anywhere

Symptom: a tool call returns nothing, or returns something truncated, and no error is shown.

Cause: two common ones. First, a local stdio server logging to stdout. The MCP docs are unambiguous that local servers must not, because stdout is the protocol channel; stderr is captured by the host and is where logs belong. One stray print() corrupts the stream. Second, output limits: Claude Code warns above 10,000 tokens of MCP output and truncates at 25,000 by default, raisable with MAX_MCP_OUTPUT_TOKENS.

Fix: get the error to surface.

claude mcp get pa                # prints an Issue: line with HTTP status and server error text
export MAX_MCP_OUTPUT_TOKENS=50000

Claude Code redacts credential-like text from that Issue line and omits the expanded server URL, since URLs can carry secrets.

14. Timeouts that look like failures

Symptom: intermittent failures, worse on the first call of a session or on long-running tools.

Cause: two separate clocks, and people tune the wrong one. A startup timeout governs how long the client waits for the server to come up; a tool timeout governs a single call.

Fix: set the one that matches your symptom.

MCP_TIMEOUT=10000 claude        # startup timeout, milliseconds

[mcp_servers.pa]
url = "https://mcp.prompt-architects.com/mcp"
startup_timeout_sec = 20        # Codex default is 10
tool_timeout_sec = 45           # Codex default is 60

In Claude Code a per-server timeout in milliseconds in the .mcp.json entry overrides MCP_TOOL_TIMEOUT for that server, values under 1000 are ignored, and remote servers also have a 60-second per-request timer up to the first response byte.

Where does each client write its MCP logs?

Fix 15 is simply knowing where to look.

Claude Desktop is the most generous of the four. mcp.log carries connection logging and failures, and each server gets its own mcp-server-SERVERNAME.log holding that server's stderr. Since stdio servers often route all logging to stderr, those files are not limited to errors. Codex is the least fixed: codex doctor is its documented diagnostic, and you should read log paths out of that report rather than assume a hard-coded one.

How do I test an MCP server outside my client?

Take the client out of the loop. The MCP Inspector is the reference tool for this and speaks to a remote Streamable HTTP endpoint directly.

# Point the Inspector at a remote server and open the web UI
npx @modelcontextprotocol/inspector \
  --server-url https://mcp.prompt-architects.com/mcp --transport http

# Or list a server's tools from the command line and pipe to jq
npx @modelcontextprotocol/inspector --cli https://mcp.prompt-architects.com/mcp \
  --transport http --method tools/list --format json | jq .

If the Inspector connects and lists tools, the server is fine and your problem lives in fixes 1 to 7. If it fails too, the cause is the endpoint, the network, or the credential. That one test halves the search space, which is why the MCP debugging guide calls it your first stop.

What does the Prompt Architects MCP server expect?

Endpoint: https://mcp.prompt-architects.com/mcp, Streamable HTTP, no port suffix, no trailing slash.

Auth: OAuth 2.1 browser sign-in for interactive clients, preferred because tokens refresh themselves. pa_live_ personal access tokens for headless and CI, sent as an Authorization bearer header. Never both at once; see fix 7.

Tools: improve, refine, shorten, enhance. Each is callable by the model and available as a slash command.

Clients: Claude Desktop, Claude.ai, Claude Code, Cursor, Codex, and Codex CLI.

The AI behind those tools is built in, so there is no third-party API key to configure on any plan, including the free one. One less category of setup failure.

If you have not set it up yet, the walkthrough is how to use MCP to manage prompts inside Cursor and Claude Desktop, and the reference is /integrations/mcp. This page is for when that one did not take.

What this looks like when it is working

A healthy setup shows four things: the server listed in the client's status panel, a status of connected rather than pending or failed, a tool count of four rather than zero, and /mcp__pa__improve returning a structured prompt. Anything less is partial success.

Get all four and MCP stops being infrastructure you think about. For teams standardising across several people, the neighbouring decisions are prompt versioning and which prompt management tooling you point everyone at. Both get easier once the connection is boring.

Sources, checked August 26, 2026: Claude Code · MCP local · MCP remote · MCP debugging · MCP Inspector · Cursor · Codex · Custom connectors