Cursor MCP Connection Failures: What to Check When a Server Does Not Appear

When a Cursor MCP connection fails, first check MCP Logs in the Output panel (Cmd+Shift+U on Mac, Ctrl+Shift+U on Windows/Linux). Then verify the mcp.json path and environment variables, and if it’s still broken, remove and re-add the server under Customize > MCPs.

This guide assumes you already wrote an mcp.json file and covers only what to do when a server does not appear in the list or fails to connect. It does not repeat the basic setup tutorial for adding a server from scratch.

Where do you look when a server does not appear in the list?

One-line answer: Re-check the mcp.json file location, then read the error in the Output panel’s MCP Logs.

Cursor reads configuration from two possible locations: project-level (.cursor/mcp.json) and global (~/.cursor/mcp.json). A typo in the filename or path will simply keep the server out of the list. If the path is correct but the server still doesn’t show up, a background error is almost always the cause, and the logs are where you find it.

  • Open the Output panel with Cmd+Shift+U (Mac) or Ctrl+Shift+U (Windows/Linux).
  • Select MCP Logs from the dropdown in the top-right corner.
  • Read the error message emitted when the server tried to start (command not found, authentication failure, etc.).

Most root causes show up here, so start troubleshooting from this step every time.

How do you check permissions, paths, and environment variables?

One-line answer: Confirm the command is on your system PATH, that shell environment variables are actually loaded into Cursor, and that auth headers are correct for remote servers.

  • Command path: for local servers, verify the command value in mcp.json (e.g. npx, python) actually runs from a terminal, meaning it exists on your system PATH.
  • Environment variables: if the server relies on variables defined in a shell profile (.zshrc, .bashrc), you must restart the shell (open a new terminal or log out and back in) after editing the profile, then restart Cursor as well before the variable is picked up.
  • Auth headers: for remote (URL-based) servers, check that the API key in the headers field (e.g. Authorization: Bearer ...) is present and not expired.

A new environment variable added to your shell profile is only visible to a Cursor instance opened after the shell itself has been restarted. Restarting only Cursor without restarting the shell can leave the variable empty.

What is the correct restart / cache-reset sequence?

One-line answer: If a plain restart doesn’t fix it, toggle the server off and on under Customize > MCPs, and if that fails, remove and re-add it.

Cached state or a leftover background process can prevent a config change from taking effect immediately. Follow this order:

  • Open Customize from the sidebar and go to the MCPs section.
  • Toggle the problematic server off and back on (enable/disable).
  • If toggling doesn’t help, remove the server from the list.
  • If you changed a shell profile or environment variables, fully quit and relaunch Cursor.
  • Go back to Customize > MCPs and click Add to Cursor to re-add the server.

Following this sequence — toggle, remove, restart Cursor, re-add — resolves most connection failures caused by stale cache or lingering processes.

Wrap-up

In short: ① check MCP Logs → ② verify path/env vars/auth → ③ toggle/remove/restart. If you’re setting up a server for the first time, refer to a dedicated mcp.json setup guide; use this article specifically to recover from an already-failed connection.