MCP troubleshooting for product managers, five failures and how to tell them apart

Where do you look first?

Two commands, in this order, before forming any theory.

claude mcp list shows every configured server and the state it is in: connected, needs authentication, failed to connect, pending approval, rejected by policy, or disabled for this project. Those states are not synonyms for broken. They are five different problems with five different fixes, and reading the state first saves you from debugging the wrong one.

claude mcp get <name> then gives the detail for a single server, including the HTTP status and the error text behind a failure. Inside a session, /mcp shows the same picture and is where re-authentication lives.

Almost everything below is one of these two commands plus a decision. The exception is the fifth failure, which neither command can see.

Failure one: it never connected

The state reads as failed to connect, and the cause is nearly always configuration rather than the server.

For a remote server, the most frequent error is a URL with no transport declared alongside it, which surfaces as a complaint about a url with no type. Adding a type of http, or sse or ws where the server uses one of those, fixes it. Beyond that, check the URL is reachable and the credentials are current.

For a local server, confirm the command exists and is executable on your machine. A local server is a program being launched, so a missing runtime or a typo in the package name produces the same failure as a broken URL does remotely.

Two quieter causes are worth knowing because they look like nothing. Claude Code warns about hidden whitespace in configuration values, leading or trailing spaces that are invisible in an editor and fatal in a URL. It also warns about environment variable references that point at a variable which does not exist, and about reserved server names that collide with built-ins. If the server is slow to start rather than broken, the startup timeout is adjustable with the MCP_TIMEOUT environment variable.

Failure two: it connected but is not authenticated

The state reads as needs authentication, or a tool call returns a 401 or a 403. This is the most common recurring failure, because it is the only one that arrives on its own: tokens expire, and a connection that worked last Thursday can be in this state on Monday with nothing having changed on your side.

The fix is /mcp, select the server, re-authenticate, or claude mcp login <name> from the command line. claude mcp logout <name> clears stored credentials when you want a clean start.

One trap here wastes real time. Certain credential variables are deliberately blocked from expanding inside a remote server's URL and headers, including ANTHROPIC_API_KEY, ANTHROPIC_AUTH_TOKEN, AWS_BEARER_TOKEN_BEDROCK, HTTPS_PROXY and NPM_TOKEN. They do not error. They read as empty, so the header goes out blank and the server answers with an authentication failure that looks like a wrong key. Copying the value into a custom variable name and referencing that resolves it.

Failure three: it is registered but not active

Here the server is fine and something is deliberately holding it back, which is why the states are distinct rather than lumped under failure.

Pending approval means a project-scoped server from .mcp.json is waiting for you to approve it in an interactive session. Rejected means a policy setting is blocking it. Disabled for this project means someone turned it off through /mcp. A strict configuration flag loads only servers passed explicitly and ignores everything else.

Scope collisions belong in this group too. The same server name registered at more than one scope resolves by precedence, running local first, then project, then user, then plugin-provided servers, then claude.ai connectors. Claude Code warns when it sees one name in several scopes pointing at different endpoints, and that warning is easy to scroll past while assuming your newest edit is the one in effect.

Failure four: it worked, and the output was cut off

MCP tool output is capped on purpose. Claude Code warns at 10,000 tokens, caps at 25,000 by default, and has a hard ceiling of 500,000 characters. When output goes over, it is written to a file and replaced in context with a reference to that file, so nothing is lost and nothing is available to reason over either.

MAX_MCP_OUTPUT_TOKENS raises the cap. Narrowing the question is usually the better move, because a request that returns 30,000 tokens of raw records is a request for a data dump rather than an answer, and the model has to read it all back to you. Long-running tools are a separate case with their own controls: a per-server timeout in the configuration and an idle timeout environment variable for tools that keep working without producing output.

Failure five: it worked, and it was wrong

This one never reports itself, which is what makes it the expensive one.

Four causes account for most of it. The permission behind the connection is narrower than you assumed, so a query returns nothing and an empty result is indistinguishable from a genuine zero. The tool list changed on the server side, which the protocol explicitly allows, and a cached discovery result means what runs is not what you last looked at. The model chose a different tool than the one you had in mind, reasonably, because two tools had similar descriptions. Or the underlying definitions disagree, and the connection faithfully reported a number built on the wrong one.

The only reliable detection is to ask. Which tool did you call, with which arguments, against which project. Then check that against what you meant. Doing this on the first three answers from any new connection is worth more than any amount of configuration care, because it is the only step that catches a system which is working exactly as configured and answering the wrong question.

There is a security-flavoured version of the same failure worth naming: the protocol's own guidance treats tool descriptions as untrusted unless the server is trusted, so a server behaving unexpectedly is not always a bug. Claude Code permissions and safety covers where the approval boundary sits around tool calls.

What to do before the next connection

Three habits close most of the gap. Verify with claude mcp list immediately after adding anything, rather than discovering at use time that a server never started. Prefer the read-only path where the vendor publishes one, as Linear does with a separate read-only endpoint, so a misconfiguration cannot write. And test every new connection on a question whose answer you already know.

That last habit is the one Builders Camp's Building with Claude Code bootcamp generalises into a system: its practical challenge is built around a team whose AI-assisted workflow broke because nobody had defined what done meant, and the exercise is designing the operating model that would have caught it automatically. It runs 1 week with 2 live sessions and 9 microlessons under Guilherme Salgueiro, alongside AI Agents on the design side, both inside the AI Agentic Builders Expert Track.

See the Building with Claude Code bootcamp

If you are still setting up rather than fixing, MCP setup for product managers covers the two routes and the scope decision, and MCP for product managers covers what the protocol is doing underneath all of this.