You run your MCP server by hand, it starts, nothing crashes. You add it to Claude Desktop, Cursor or another client and it shows up red, "failed", or connects and then no tool works.

Almost always the server is fine. The difference is the environment the client launches it in. These are the seven causes we keep hitting, roughly in order of how often.

1. Something writes to stdout

With the stdio transport, stdout IS the protocol. Every byte on it must be a JSON-RPC message. One console.log("server started"), a banner from a library, or a deprecation warning printed to stdout, and the client fails to parse the stream.

Fix: send all logs to stderr (console.error in Node, print(..., file=sys.stderr) in Python, the logging module defaults to stderr). Clients usually capture stderr into their log file, so you lose nothing.

2. The client does not have your shell's PATH

On macOS, an app started from the Dock or Finder does not read .zshrc or .bash_profile. It gets the minimal launchd PATH, /usr/bin:/bin:/usr/sbin:/sbin. If node came from Homebrew (/opt/homebrew/bin) or nvm (~/.nvm/versions/...), the client cannot find npx or node, and you get spawn npx ENOENT.

Fix, pick one:

• Use the absolute path as the command: run which npx in your terminal and paste the result.
• Set PATH explicitly in the server's env block in the client config.

With nvm, the absolute path also pins the Node version, which avoids cause 6.

3. Your environment variables are not there either

The same applies to API keys and settings you exported in your shell. The server process only gets what the client passes it.

Fix: put them in the env block of that server's config entry, not in your shell profile.

4. npx is waiting or still downloading

npx some-package on a machine that does not have it cached first downloads it. Without -y it can stop to ask "Ok to proceed?", and nobody is there to answer. Even with -y, a slow first download can outlast the client's startup timeout, so the first launch fails and the second one works.

Fix: always npx -y, and run the exact command once in a terminal so the package is cached before the client starts it.

5. Relative paths and the working directory

Clients do not promise a working directory. On macOS it is often /. A server that opens ./config.json or writes ./data.db works from your project folder and fails everywhere else.

Fix: absolute paths in args, or resolve paths relative to the script file, not the current directory.

6. A different Node or Python than you think

Your terminal uses the version from nvm, pyenv or a virtualenv. The client may hit the system one, or an old Homebrew one. Syntax errors at import time or "unsupported engine" warnings in the log are the sign.

Fix: point the command at the exact interpreter (/path/to/venv/bin/python, the nvm node), not a bare python or node.

7. Windows: npx is not an executable

On Windows npx is npx.cmd, a batch file, and some clients spawn the command without a shell, so "command": "npx" fails.

Fix: launch it through cmd:

{
  "command": "cmd",
  "args": ["/c", "npx", "-y", "your-mcp-package"]
}

Where to look first

• Claude Desktop logs: ~/Library/Logs/Claude/ on macOS (mcp.log plus one mcp-server-<name>.log per server), %APPDATA%\Claude\logs on Windows. Your stderr ends up there.
• Claude Code: claude mcp list shows which servers connect, and /mcp inside a session shows their status.
• MCP Inspector: npx @modelcontextprotocol/inspector <your command> <args> starts the server the way a client would and lets you call each tool by hand. If it works there and not in the client, the problem is the client's environment (causes 2 to 6).
• Restart for real. Most clients read the config only at startup. On macOS that means Cmd+Q, not closing the window.

A 30-second checklist

• Nothing but JSON-RPC on stdout?
• Command is an absolute path, or PATH is set in env?
• API keys in the config's env, not only in your shell?
• npx -y, and the package already cached?
• No relative paths?
• The interpreter the client runs is the one you tested with?
• On Windows, cmd /c npx?

Why we wrote this

We build Auten, an MCP server that gives Claude Code, Codex, Cursor or any MCP client hands on a real screen: your computer and your Android phone (beta). It is launched with npx -y @autenai/mcp, so every item on this list is a support question we have either hit ourselves or expect to.

Hit an eighth cause? Put it in the comments and we will add it.

You wire a computer-use MCP server into Claude Code, Cursor or Codex, ask it to click a button, and the tool call comes back "ok". Nothing on screen moves. Or the screenshot it reasons over is just your wallpaper.

Nine times out of ten this is not the model and not the MCP server. It is macOS privacy permissions (TCC), and the frustrating part is that most of the failures are silent. This is the checklist we wish we had on day one.

Two permissions, two different failures

A screen-driving agent needs two separate grants in System Settings > Privacy & Security:

Accessibility lets a process read other apps' UI trees (buttons, fields, labels) and post synthetic mouse and keyboard events.

• Without it, Accessibility API calls fail with kAXErrorAPIDisabled (-25211). Many tools swallow that and return an empty element list.

• Synthetic events posted with CGEventPost are dropped without any error. The click "succeeds" and nothing happens.

Screen Recording lets a process capture other apps' pixels.

• Without it, a capture typically shows the desktop and menu bar, but not the contents of other apps' windows. A vision model then confidently describes an empty desktop.

• Less obvious: window titles of other apps (kCGWindowName from CGWindowListCopyWindowInfo) are withheld too, so "find the window called Invoice" fails even if you never take a screenshot.

If your agent can list elements but its screenshots look empty, you are missing Screen Recording. If it can see everything but clicks do nothing, you are missing Accessibility.

The grant usually belongs to the app hosting your agent

This is the part that costs people an afternoon. macOS attributes a permission request to the "responsible" app, which for a command-line tool is usually the GUI app that launched it, not the binary itself.

• MCP server started by Claude Code in Terminal or iTerm: the grant Terminal (or iTerm) has is what counts.

• Started by Cursor, VS Code or a desktop chat client: that app's grant counts.

• Started by launchd (a LaunchAgent): the process itself is responsible, so the grant has to be on the exact binary in ProgramArguments.

So "I gave node Accessibility and it still fails" is normal: node was never the responsible process. Grant the host app, restart it fully (quit, not just close the window), and try again. Permission changes are not picked up by already running processes.

The flip side is worth saying plainly: granting Accessibility to Terminal means everything you run from Terminal can drive your Mac. If that bothers you, run the agent from a dedicated terminal app you use only for it.

Check what your agent actually has

Run this from the same app that launches your agent, so it inherits the same responsible process:

cat > /tmp/tcc-check.swift <<'EOF'
import ApplicationServices
import CoreGraphics
print("Accessibility:   ", AXIsProcessTrusted())
print("Screen Recording:", CGPreflightScreenCaptureAccess())
EOF
swift /tmp/tcc-check.swift

Both functions only check, they never show a prompt. false on either line explains most "it does nothing" reports. (Needs the Xcode command line tools for swift.)

To watch macOS decide in real time while your agent tries to act:

log stream --debug --predicate 'subsystem == "com.apple.TCC"'

The log shows which process TCC evaluated and whether it was allowed, which settles the "who is responsible" question without guessing.

The toggle is on, and it still fails

Three causes we keep running into:

1. The binary changed. A grant is tied to the code signature. For an ad-hoc signed binary that means its exact hash, so every rebuild, or a package-manager upgrade that replaces the binary, silently invalidates the grant while the switch in Settings still shows "on". Fix: remove the entry with the minus button and add it again, or sign your own tools with a stable identity (a free Apple Development certificate is enough).

2. Stale entries. Reset one service for one app and let it ask again:

   tccutil reset Accessibility com.apple.Terminal
   tccutil reset ScreenCapture com.apple.Terminal
   

   Use the bundle id of whichever app hosts your agent.

3. A pending system prompt. Recent macOS versions periodically ask you to reconfirm screen access for some apps. An unattended agent cannot answer that dialog, so if captures suddenly go blank after weeks of working, look at the screen for a waiting prompt first.

A short pre-flight before you blame the model

• Which app launches the agent? That app needs both grants.

• Fully quit and reopen it after granting.

• Run the Swift check from that app: both true?

• Screenshots empty -> Screen Recording. Clicks ignored -> Accessibility.

• Toggle on but failing after an update -> remove and re-add the entry.

Why we care

We build Auten, an MCP server that gives Claude Code, Codex, Cursor or any MCP client hands on a real screen: your computer and your Android phone (beta). On macOS, its installer runs a permissions setup step and auten status shows what is connected and what is missing, because silent permission failures were the first thing that broke for us too.

If you are hitting a TCC case not covered here, describe it in the comments. We collect these.