Common MCP Server Setup Mistakes

Most MCP setup pages fail in the same way: they show the happy-path config, the user pastes it, and the next problem gets treated like some deep protocol mystery.

It usually is not. The repeat offenders are more boring than that:

• the server was added in the wrong scope
• the host can see the server but not the credentials
• Windows launched npx the wrong way
• the first proof task depended on private state, hidden login, or too many moving parts
• the user added multiple servers before a single one actually worked

This page is not a generic “top 10 mistakes” list. It is a recovery page for the setup problems that keep showing up in real GitHub MCP and Playwright MCP installs.

Fast Answer#

• If the server is not visible at all, check scope and registration first, not prompts.
• If the server is visible but cannot access private repos or protected resources, check auth before changing transport.
• If you are on native Windows and the server uses npx, assume the launch command may be wrong until proven otherwise.
• If the browser opens but the result is inconsistent, treat stale session state and task shape as the first suspects.
• If you added more than one MCP server before finishing one proof task, simplify the stack before debugging anything else.

Start With The Failure Bucket, Not With Random Edits#

Before you touch config again, decide which of these three buckets you are actually in:

1. The server does not appear in the host.
2. The server appears, but the host cannot use the resource you expected.
3. The server appears and runs, but the first task still behaves badly.

That classification matters because each bucket points to a different layer:

• missing server usually means registration, scope, file path, or local launcher problems
• visible but unusable server usually means auth, permissions, or transport mismatch
• visible and runnable but low-confidence output usually means stale state, noisy task design, or too many tools

If you skip this split, you usually end up editing the wrong layer.

Click to enlarge

Use this as the shortest triage path: first decide whether the server is missing, unauthorized, or just producing a noisy first run. The fix changes depending on that split.

Mistake 1: Adding Multiple Servers Before One Works#

This is the most common setup error because it feels productive.

Someone adds GitHub MCP, then Playwright MCP, then maybe Linear, then tries one ambitious task and gets a blurry failure. At that point there is no clean answer to the basic question: which server actually broke the workflow?

The cure is subtraction:

• keep one host
• keep one server
• keep one task
• prove one success condition

For GitHub MCP, that means reading one repo and one issue or PR cleanly.

For Playwright MCP, that means opening one public page, changing one visible state, and reporting the result accurately.

If that sounds too narrow, that is the point. MCP stacks usually break from connector sprawl earlier than they break from lack of capability.

Mistake 2: Putting The Server In The Wrong Scope Or Config Location#

This is where a lot of “it worked yesterday” confusion starts.

Claude Code and Cursor both support multiple MCP config locations, but they do not behave the same way:

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

That means a server can be genuinely configured and still not be available in the place you are testing.

Typical examples:

• you added a Claude server with the default local scope in one repo, then tested in another repo
• you wrote a project-scoped config and forgot that Claude requires approval for project MCP servers from .mcp.json
• you saved Cursor config under the project path, but expected it to appear globally
• you edited the right file, but the app never reloaded the MCP configuration

Use the host's own inspection surface before editing more config:

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

If the server is not visible there, the prompt is not the problem yet.

Mistake 3: Trusting npx To Behave The Same On Every OS#

This one is specific enough that it deserves to be memorized.

Anthropic's MCP docs explicitly call out native Windows as a special case: when a local MCP server is launched through npx, Claude Code needs the cmd /c wrapper. Without it, the server can fail with Connection closed even though the package name looks right.

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

The practical rule is simple:

• on macOS, Linux, and WSL, start with the plain local command
• on native Windows, suspect the launcher before you suspect the package

If the server is failing instantly on native Windows, do not waste twenty minutes rewriting the same config in different shapes. Fix the process launch first.

Mistake 4: Treating Auth As “Probably Fine”#

If the server is visible but the resource is missing, auth is the first boring thing to check.

GitHub MCP is the clearest example. GitHub's own docs and troubleshooting notes keep pointing back to token quality and repo access:

• private repos not showing up
• org access missing
• token present in config but not actually available to the running host
• project config committed without a safe env-var path, so teammates inherit a broken definition

The trap here is visual confidence. A server can appear healthy in the host and still be using the wrong token or no usable token at all.

Do this instead:

1. verify the server is visible
2. verify the token path the host is supposed to read
3. test the smallest protected resource, not the whole workflow

For GitHub MCP, that means one private repository or one private issue, not a multi-step repo-plus-browser task.

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

Mistake 5: Debugging The Wrong Transport#

People often switch transports too early.

If the real problem is bad auth, moving from hosted HTTP to Docker will not save you.

If the real problem is a brittle local launcher, changing the token will not save you.

The transport question only becomes useful after you know which layer is failing:

• local stdio is the shortest first path when the launcher is reliable
• hosted HTTP is cleaner when the host supports it well and auth is straightforward
• separate HTTP or Docker fallback is useful when local process launch is the unstable layer

This is why the GitHub MCP and Playwright MCP guides both have a “shortest path first, fallback second” shape. The fallback exists for a reason, but it is still a fallback.

A good sign that you are debugging the wrong transport is when every attempt fails in the same way regardless of transport. That usually means the problem is auth, scope, or task shape instead.

Mistake 6: Using A Bad First Task#

This is the setup error that looks least technical and wastes the most time.

The first task should not require:

• login to a fragile internal app
• hidden product knowledge
• multiple MCP servers
• browser plus repo plus deployment actions in one run

That is why the current setup pages in this project keep using small proof tasks:

• GitHub MCP: read one repo and one issue or PR
• Playwright MCP: use TodoMVC or another public page with obvious visible state

If the first task is noisy, you cannot tell whether the integration failed or the task was just badly chosen.

For browser-first setups, there is one extra wrinkle: Playwright MCP uses a persistent profile by default. That can make a flaky test look like a real success because old cookies or old session state are still around. When the first run behaves oddly, a clean or isolated browser session is often the better second test than rewriting the prompt again.

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 is not glamorous, but it is the fastest path back to signal.

When To Stop Debugging And Change The Stack#

Sometimes the problem is not setup quality. Sometimes the stack itself is wrong for the job.

Examples:

• you keep adding Playwright when the real missing layer is still repository context
• you keep forcing GitHub MCP when the real work starts in a browser, not in issues or PRs
• you are using a terminal-native host even though the team really wants editor-native review

That is not a troubleshooting failure. It is a stack-choice failure.

When that happens, move sideways instead of going deeper:

• from browser-first confusion back to GitHub MCP Server
• from repo-only limits toward Playwright MCP
• from host uncertainty toward Cursor vs Claude Code
• from broad connector confusion back to How To Choose An MCP Server For GitHub Workflows

Official References#

These sources shaped the recovery logic 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 failure is GitHub-specific, open Setup GitHub MCP Server with Cursor or Claude Code.

If your current failure is browser-specific, open Setup Playwright MCP with Claude Code.