Cursor says MCP is connected. So why aren't the tools there?

A server can look connected while its tools never arrive. Compare two numbers before anything else: the tool count on the server's row in Customize → MCPs, and the tools list at the top of the chat (CLI: /mcp in the session).

MCP (Model Context Protocol) is how Cursor reaches tool servers declared in .cursor/mcp.json (project) or ~/.cursor/mcp.json (user). Both files load, and a project entry wins on a name collision (MCP help). Cursor connects, asks the server what it can do, and puts the definitions it gets back in the model's context. "Connected" covers only the handshake: a server can be connected with zero tools, or with thirty tools that never reach the chat, the Agents Window, the CLI, a cloud run, or a worktree.

Run Cursor → About Cursor (CLI: agent --version; agent about adds account and system details). The Customize project-server listing was fixed in 3.17, and older builds may still show MCP under Settings → Tools & MCP. Current CLI docs call the command agent; older posts say cursor-agent.

Checked against Cursor's documentation and changelog on 27 October 2026.

Status, 27 October 2026: a non-stdio server's tool list can stay at its startup version; staff say reconnect and Reload Window can fail to refresh it, and it was still reported on 3.24.12 on 20 October 2026 (#166216). In the CLI, a project server can show ready in agent mcp list while a session skips it because the per-project approval was saved under a different identity on Windows (staff, #171696, 15 September 2026).

Start with the count#

Open Customize → MCPs and read the tool count on the server's row; Output → MCP Logs also lists prompts and resources. Zero tools means the server connected but gave Cursor no tools. Above zero means discovery worked; if the chat's tools list is still empty, the problem is downstream, in the surface, the run mode, or the model. A server toggled off does not load, even if its row stays visible (MCP help).

Connected is one stage, not the answer#

The status dot — green in most screenshots — and the word Connected are transport status. They do not say the server returned tools, that those tools reached this chat, or that the run mode let the model call them.

Tools are functions the model can call; resources are data the client can read; prompts are templates. Cursor supports all three. A server can expose tools and no resources; that is not a tool failure (MCP reference).

The server returned no tools#

In the editor, open Output → MCP Logs. Look for the line that says how many tools were found, such as "Found 14 tools, 0 prompts, and 0 resources." "Found 0 tools" means the server answered and offered nothing.

Run the server by hand, or use agent mcp list-tools <server>. agent mcp list may only say "Connection failed", while list-tools appends stderr (#175740, staff 22 October 2026). Check the command, arguments, working directory, environment, and auth.

On Windows, staff found the CLI gives stdio servers (local processes Cursor starts) a short base environment plus the entry's env, while the IDE passes its full environment. Missing PATHEXT, ComSpec, windir, ProgramData, proxy or DOCKER_* variables can break a wrapper; adding PATHEXT and ProgramData fixed it for the reporter (#175740, 22–26 October 2026). The CLI also does not load envFile yet (22 October 2026), so put those variables in env for a CLI test.

The server returned tools, Cursor shows none#

Two causes look the same from the chat.

A large tools/list (the server's tool list) can be dropped silently. In May 2026 staff confirmed a response of about 287 KB was discarded while the log still said 14 tools; stripping outputSchema cut it to about 41 KB and the tools appeared (#160620, 16 May 2026). That is a Cursor-side silent drop, not a setting; the workaround is to shrink the payload, and the real fix is Cursor's.

The other is the cache. For non-stdio servers, Cursor can keep the list it loaded at startup after the server or mcp.json changes. Staff say reconnect and Reload Window can fail to clear it, and it was still reported on 3.24.12 on 20 October 2026 (#166216). Staff suggested the server's notifications/tools/list_changed signal or a changed hashed key (a dummy query parameter on the URL), with a full quit as the reliable fallback; the reporter found list_changed did not work on 3.12.17. A new chat resets the chat, not the cache.

Removed tools can linger because Cursor writes a JSON file per tool under ~/.cursor/projects/<project-slug>/mcps/<server-id>/tools/; staff confirmed the UI and agent follow that on-disk set. A full quit is the reset, not hand-deleting files (#166216, 24 August 2026).

Connected, but the calls fail#

A server can be connected with a valid tool list and fail every call. Staff described connected with auth=unknown: the row is healthy, the tools are listed, and each call returns Unauthorized. The transport is up; the token is not valid (#160234, 23 May 2026).

Sign out and back in. Check the OAuth client type and redirect URL; for Google-hosted servers, staff said the client must be a Desktop app, not a Web app, for the custom-scheme callback. Cursor renews a token when the server issued a refresh token; if not, you sign in when it expires, and offline_access providers need that scope (MCP reference).

If the server is not in the list at all#

Customize groups by user, workspace, and team; a project server is under the folder that owns it, not User (MCP help).

• The build. Project servers could be connected and usable while Customize showed an empty list after the mid-2026 Customize rollout, including in multi-root workspaces. Staff said on 26 August 2026 that the fix had landed in 3.17 (#167704, #167808); on an older build, open the owning folder alone or use the editor chat.
• The admin. A team MCP allowlist can block a server before it starts; staff described exact command-string matching with no path normalization (#175740, 22 October 2026). If MCP Network Controls are on, command servers run in a sandbox; Windows has no sandbox, so they do not start and the log says so. An admin can add a Command entry with No sandbox (MCP help).
• The plugin. A plugin can bundle an MCP server; check the MCP list, not just the plugin's install state, because a toggled-off server does not load (plugins).

If the count is right but this surface has no tools#

Customize tells you what Cursor discovered, not what this chat, window, terminal, or cloud run received.

CLI. agent mcp list can show a project server as ready while a session skips it. Project servers need a per-project approval; servers in ~/.cursor/mcp.json load without one. On Windows, staff found the session and agent mcp enable compute the approval under different project identities. --approve-mcps skips the check for one session and saves nothing; moving the server to the global file avoids it (#171696, staff 15 September 2026). /mcp shows the session's view and can log in, enable, or disable a server; the changelog says those actions refresh the tools immediately (20 May 2026).

Cloud Agents. Add personal servers from the MCP dropdown at cursor.com/agents; team admins configure shared servers under Dashboard → Plugins & MCPs. OAuth is per user even for team servers, and sign-ins live on Cursor's servers, so a local sign-out does not sign out a cloud agent (MCP reference). Custom servers can use HTTP or stdio; SSE and mcp-remote are not supported (cloud capabilities). Cloud Agents do not use Run Modes. If auth fails, the run dashboard records mcp_auth_error, the tools are skipped, and the run continues — a green run is not proof the tools were there (cloud capabilities).

Agents Window and worktrees. The Agents Window is Cursor's separate agent-first interface, not the editor chat. Over Remote SSH, the editor uses the remote extension host, but the Agents Window resolves user config locally; a project .cursor/mcp.json on the remote repo works (staff, 23 July 2026, #166469). A new worktree (a separate Git checkout) is a new workspace path: approval and OAuth are scoped to it, so an OAuth server starts configured but not enabled. Staff said in October 2026 there is still no reliable non-manual workaround; an API key or PAT is the practical path (#159989, last staff reply 17 October 2026).

If the tool is there and the agent won't call it#

In the editor, open the tools list at the top of the chat. Toggle the tool on if it is off. Then check the run mode, which decides when Cursor asks before a tool call. Auto-review (the default since 3.6) runs allowlisted MCP tools and sends the rest to a Cursor-managed classifier; Allowlist runs only allowlisted actions without asking; Run Everything runs all calls (run modes).

In the editor, if it keeps asking, add server:tool to mcpAllowlist in ~/.cursor/permissions.json; per-repo allowlists are not read on current builds. my-server:* allows all tools from a server; *:* allows all. The docs say an empty array is an empty allowlist; a reported test found it can fall back to saved entries (permissions guide). Allowlists are not a security boundary (permissions reference).

The model is the last layer. A tool definition is an option, not an instruction. Name the server and tool and ask for a harmless call: "Use the Linear MCP's list_issues for team ENG and show the first row." A tool call with a result is the proof. If the tool is missing from the list, the model never had it; if it is present and refuses, that is adherence, not discovery.

Tool definitions also take context. In the editor, the context ring next to the prompt has an MCP row showing instructions and the catalog; disabling unused servers is the documented way to cut clutter (prompting, MCP help).

Don't ask the model#

A model sees a prompt, not the client's registry. It will say it has the tool because the definition is in context, or say it does not because it cannot find a call; both are generated text. The tool count, MCP logs, the chat's tools list, and a real call are the evidence. If you open a thread, copy the Request ID from the chat's three-dot menu; staff ask for it with the MCP log (#149163, staff 25 February 2026).

Where to go next#

• Cursor guides — the rest of the set.
• Why your Cursor rule isn't applied — when the missing instruction is a rule.
• Why Cursor keeps asking for permission — when the approval layer keeps blocking the tool.
• Why your Cursor hook doesn't fire — when the missing piece is a hook.