Cursor MCP server not connecting, or its tools not showing: the fixes

Start with MCP Logs

Cursor writes MCP activity to its own log. Open the Output panel with Cmd+Shift+U on macOS or Ctrl+Shift+U on Windows and Linux, and choose MCP Logs from the dropdown. The log shows each server starting up, every tool call and the errors: a command that wasn't found, a server that crashed, a 401 from a remote server, a sign-in that failed.

Next, open Customize in the sidebar and go to MCPs. Each server there has a toggle, and a server that is off doesn't load or appear in chat. The Cursor CLI reads the same configuration: agent mcp list shows each server's status, where its config came from (project or global) and its transport, and agent mcp list-tools <name> lists the tools it returned.

The server isn't listed: check the file

• Cursor reads two files: ~/.cursor/mcp.json for every project and .cursor/mcp.json in a project folder. It merges both, and when a server name appears in both, the project file wins.
• Servers go under an mcpServers key. A file copied from VS Code, whose mcp.json uses a top-level servers key, won't load in Cursor as written.
• Local servers need command, plus args and env as needed. Remote servers need url, and headers for a token. Cursor accepts Streamable HTTP and SSE URLs.
• Cursor's help says to save the file and restart Cursor. Toggling the server off and on in Customize > MCPs also reloads it.

{
  "mcpServers": {
    "my-remote": {
      "url": "https://mcp.example.com/mcp",
      "headers": { "Authorization": "Bearer ${env:MY_SERVICE_TOKEN}" }
    },
    "my-local": {
      "command": "npx",
      "args": ["-y", "some-mcp-server"],
      "env": { "API_KEY": "${env:API_KEY}" }
    }
  }
}

The server fails to start

• The command has to be on Cursor's PATH or written as a full path. A tool installed by a version manager that only your shell profile loads may not be visible to Cursor.
• Variables exported in your shell profile reach the server only if Cursor can see them. Cursor's help says to make sure they are available to Cursor and to restart Cursor after changing the profile. A stdio server can also read them from a file with envFile (for example "${workspaceFolder}/.env"); remote servers don't support envFile.
• Relative paths in args are a common miss. Build the path from ${workspaceFolder}, the folder that holds .cursor/mcp.json.
• On Windows, when an admin has turned on MCP Network Controls, command servers that need the sandbox don't start, and MCP Logs say the server requires sandboxing. The admin can add a Command entry with the No sandbox network mode.

Connected, but the agent has no tools

• Tools can be switched off one by one. Click a tool's name in the tools list at the top of the chat panel to turn it back on.
• A server that uses OAuth connects only after you sign in. Finish the sign-in from Customize > MCPs, or run agent mcp login <name> in the CLI. If the provider issues refresh tokens only for a scope such as offline_access, add that scope to auth.scopes, or Cursor asks you to sign in again each time the token expires.
• Cloud Agents keep their own MCP sign-ins on Cursor's servers. Signing in on your machine doesn't sign them in.
• In the Cursor CLI, a server you haven't approved doesn't load. agent mcp enable <name> adds it to the local approved list, and agent --approve-mcps approves every configured server for that run.
• On a team plan, an enterprise admin's MCP allowlist decides which servers and tools may run. Check Team Settings > MCP Configuration if a server works on a personal account but not on a work one.

Once the tools load, Cursor asks before it runs an MCP tool by default. In Cursor 3.6 and later, the Auto-review mode under Cursor Settings > Agents > Approvals & Execution runs allowlisted MCP tools right away and sends the rest through a safety classifier.

Taskhold-specific checks

Taskhold is a remote server at https://taskhold.com/api/mcp. When the taskhold tools don't show up in Cursor, check these in order:

1. The entry sits under mcpServers in ~/.cursor/mcp.json (or the project's .cursor/mcp.json) with url set to https://taskhold.com/api/mcp. A fresh setup URL from Settings, pasted into the chat with "set this up", writes it for you.
2. With a key, the header is Authorization: Bearer followed by a key that starts with atd_sk_. A 401 in MCP Logs names the problem: missing_key, bad_header, not_a_taskhold_key or unknown_key. With ${env:TASKHOLD_API_KEY}, the variable has to reach Cursor (see above).
3. Added just the URL with no key? Finish the sign-in from Customize > MCPs; a browser window asks you to sign in to Taskhold and allow Cursor.
4. A 402 means the key works but the trial ended or the plan was canceled. Restarting the plan fixes it with no config change.
5. Settings in Taskhold shows Connected once the first call arrives. Ask the agent to call taskhold_list to test.

With the tools loaded and the rules snippet from the Cursor page in place, every task Cursor starts, its steps and its questions show on the live board. Running Cursor next to Claude Code? Both can share one list: see a shared todo list for Claude Code and Cursor. The same checks for other clients are in Claude Code MCP server not connecting and Codex CLI MCP server not loading.