Common MCP Server Setup Mistakes

Most MCP setup failures are not really "setup" failures.

They are classification failures.

People see one vague symptom, then start changing scope, transport, auth, prompt wording, and host settings all at once. After ten minutes, the original signal is gone and the stack looks more broken than it was.

The boring truth is that most first-install problems still land in one of three buckets:

• the host cannot see the server at all
• the host can see the server, but not the resource you need
• the host can see the server and call it, but the first task is too noisy to trust

This page is for that moment. It is not a long list of trivia. It is the shortest way back to a clean first MCP proof run.

If You Only Check Three Things#

• Missing server: inspect scope, config location, and process launch before touching prompts.
• Visible server but missing data: assume auth or permissions before you assume transport.
• Visible server with chaotic output: blame the first task before you blame the protocol.

Start By Naming The Failure, Not The Tool#

Before you edit config again, decide which failure you actually have:

1. The server does not appear anywhere in the host.
2. The server appears, but it cannot reach the repo, page, or protected resource you expected.
3. The server appears and runs, but the first result is still messy or misleading.

That split matters because each bucket points at a different layer:

• missing server usually means registration, scope, file path, reload, or process launch
• visible but blind server usually means auth, permissions, or the wrong runtime context
• visible and runnable but low-trust output usually means a bad first task, stale browser state, or too many tools in the loop

If you skip this step, you usually debug the wrong thing for half an hour.

Click to enlarge

Use this as a routing shortcut. The point is not to memorize MCP theory. The point is to stop editing the wrong layer.

When The Server Is Missing, Stop Touching Prompts#

If the host cannot see the server, the problem is almost never your prompt.

It is usually one of these:

• the server was added in the wrong scope
• the config file is valid, but not the one this host is reading
• the host never reloaded the MCP definition
• the local launcher is failing before the server comes up

The scope problem is common because Claude Code and Cursor both support more than one config location, but they do not treat those locations the same way:

• Claude Code has local, project, and user scope
• Cursor can load from ~/.cursor/mcp.json or .cursor/mcp.json

That creates a very ordinary failure mode: the config exists, but not in the place you are testing.

Typical examples:

• you added a Claude server with default local scope in one repo, then tested in another
• you expected a project-scoped server to appear without approving the .mcp.json file
• you edited .cursor/mcp.json, but were actually testing outside that project
• you wrote the right config, but never forced the host to reload it

Use the host's own inspection surface before you do anything else:

• Claude Code: claude mcp list, claude mcp get <name>, or /mcp
• Cursor: the MCP settings screen and visible tool list in chat

If the server is not listed there, stay at the registration layer until it is.

On Native Windows, Suspect The Launcher Early#

This is worth memorizing because it keeps wasting time.

Anthropic's MCP docs call out native Windows as a special case for npx-launched local servers. Without the cmd /c wrapper, Claude Code can fail with Connection closed even when the package name is correct.

That matters most for pages like Setup Playwright MCP with Claude Code, where the shortest install path uses npx.

The practical rule is plain:

• on macOS, Linux, and WSL, start with the direct local command
• on native Windows, suspect process launch before you suspect package syntax

If the server dies instantly on Windows, do not burn time rewriting JSON in three different places. Fix the launcher first.

When The Server Is Visible But Blind, Auth Beats Transport#

This is where people lose the plot.

The server appears healthy, so they assume auth must already be fine and start changing transport instead. That is backwards.

GitHub MCP is the clearest example. A server can show up perfectly in the host and still fail on the only thing you care about:

• the private repo does not appear
• the org repo is missing
• the PAT is present in config, but not actually available to the running host
• the token can see public repos, but not the protected resource you picked for the first proof

The right order is dull, which is why it works:

1. confirm the server is visible
2. confirm where the credential is supposed to come from
3. test one small protected resource

For GitHub MCP, that means one private repo or one private issue. Not repo-plus-browser. Not a full code task. One protected read.

For remote HTTP servers, it also means checking whether the host wants headers, OAuth, or environment expansion in a different place than you assumed.

When The Server Runs But The Result Is Still Chaotic, The Task Is Usually Bad#

This is the least technical mistake and the one that wastes the most time.

The first task should not require:

• private app state
• fragile login flows
• multiple MCP servers
• hidden business knowledge
• browser, repo, and deployment actions in one turn

Good first proofs are intentionally boring:

• GitHub MCP: read one issue or pull request and name the likely files
• Playwright MCP: open one public page, change one visible state, and report what happened

If the first task is noisy, you cannot tell whether the server is broken or the test itself is bad.

Browser setups have one extra trap: Playwright MCP uses a persistent profile by default. That can make a flaky test look successful because old cookies or remembered state are still helping. If the first browser run behaves strangely, a clean or isolated second run is usually smarter than rewriting the prompt again.

Two Ways Teams Waste The Next Hour#

Adding More Servers Before One Works#

This feels productive and is almost always counterproductive.

Once GitHub MCP, Playwright MCP, and maybe one planning connector all enter the same broken test, you can no longer answer the basic question: which part failed?

Cut back to:

• one host
• one server
• one proof task
• one success condition

That is not overly cautious. It is the only way to get signal back.

Switching Transport Before You Know The Failure Layer#

Moving from hosted HTTP to Docker, or from local stdio to HTTP, only helps when the failing layer is actually transport or process launch.

It does not help when the problem is:

• wrong scope
• wrong file
• wrong token
• wrong first task

If every transport fails in the same vague way, you probably are not looking at a transport problem yet.

The Shortest Recovery Sequence#

When you are no longer sure what is broken, do this in order:

1. Remove every extra MCP server from the test except the one you are debugging.
2. Confirm the server is visible in the host's own inspection surface.
3. Confirm the scope or config file is the one you are actually running from.
4. Re-check auth or env variables on the smallest protected resource.
5. Switch transport only if the failure clearly points to the launcher layer.
6. Re-run one boring public proof task before touching your real workflow again.

This sequence is boring on purpose. Recovery gets faster when the stack gets smaller.

Sometimes The Real Fix Is To Change The Stack#

Not every stubborn setup problem is a setup problem.

Sometimes you are just forcing the wrong server or the wrong host into the job:

• you keep adding Playwright even though repository context is still the missing layer
• you keep pushing GitHub MCP even though the real uncertainty is in the browser
• you keep testing in a terminal-native host even though the team reviews and iterates in the editor

That is not a technical failure. It is a routing mistake.

When that happens, move sideways instead of digging deeper:

• from repo-first work to GitHub MCP Server
• from browser-evidence work to Playwright MCP
• from host confusion to Cursor vs Claude Code
• from connector sprawl back to How To Choose An MCP Server For GitHub Workflows

Official References#

These sources informed the troubleshooting order above:

• GitHub MCP Server Repository
• Anthropic Docs: Connect Claude Code to tools via MCP
• Cursor Docs: Model Context Protocol
• Playwright Docs: Playwright MCP

Next Step#

If your current problem is repo access or PAT handling, open Setup GitHub MCP Server with Cursor or Claude Code.

If your current problem is browser launch, browser state, or first-page verification, open Setup Playwright MCP with Claude Code.