MCP Auth Fail: What to Do on needsAuth

MCP auth failure is a different axis from connection failure (unread mcp.json or a process that never starts). The server card still appears under Customize, but its status is needsAuth (or authentication required), Available Tools is empty, or tool calls fail immediately. No pricing, plans, token counts, or raw API key values.

This post covers only symptoms, reconnect order, and empty tool lists. Grounded in the Cursor MCP docs on OAuth, debugging, and toggles. If the server never appears in the list at all, use the separate mcp-connection-fail piece instead.

What are the symptoms?

One-line answer: The server is visible but needsAuth, and MCP Logs show OAuth / 401 / invalid_token style messages → auth axis. Command-not-found and path typos → connection axis.

How to tell connection fail from auth fail:

Signal	Connection fail	Auth fail (needsAuth)
Customize list	Missing, or dies right after start	Present, status needsAuth / Authenticate
MCP Logs	command not found, spawn fail, bad JSON	OAuth, callback, 401, invalid_token, needsAuth
Chat tools	Server absent from Available Tools	Server present but zero tools / calls rejected
Fix surface	mcp.json path, command, PATH, env	OAuth re-auth, toggle, Logout then Authenticate

Patterns you see in practice:

1. A marketplace/plugin remote server (Linear, Atlassian, Figma, …) worked, then suddenly shows needsAuth.
2. The browser OAuth window opens, but Cursor stays needsAuth after the callback.
3. One workspace stays connected while another Cursor window/profile loops on needsAuth.
4. Local stdio servers start; only url remotes stick on OAuth.

Per the docs, remote transports (SSE / Streamable HTTP) can use OAuth; stdio usually passes keys via env. needsAuth is closest to “no valid OAuth session (missing, expired, or invalid).” A typo that keeps the server off the list is out of scope here.

What is the reconnect order?

One-line answer: Confirm auth messages in MCP Logs, then Authenticate → (if stuck) toggle off/on → Logout and re-auth → restart Cursor. Do not delete mcp.json first.

Recommended order (aligned with the MCP FAQ on logs and toggles):

1. Open Output → MCP Logs (Cmd+Shift+U on Mac, Ctrl+Shift+U on Windows/Linux). Pick MCP Logs in the dropdown.
2. Look for needsAuth, OAuth callback, 401, invalid_token. If those are absent, suspect connection/path first.
3. In Customize → MCPs (or the plugin card), click Authenticate / login and finish the browser OAuth flow.
4. If still needsAuth after the callback, toggle the server off and on. Docs/forum guidance: stuck auth is re-triggered by the toggle.
5. Still stuck → Logout / Disconnect, then Authenticate again. That clears an expired or workspace-scoped session tangle.
6. Restart Cursor fully only after shell/profile changes. Deleting mcp.json while the real issue is auth creates a new connection problem.

If the provider requires a fixed Client ID, you may need Static OAuth (auth.CLIENT_ID, …) and registered redirect URLs from the docs:

• Desktop: http://localhost:8787/callback
• Web / Agents: https://www.cursor.com/agents/mcp/oauth/callback

Register those as allowed redirects in the provider console—do not paste secrets into posts or screenshots. Put key names in env / headers; keep values local.

Boundary vs the connection-fail post: path / PATH / env / remove-and-re-add is the connection axis. On needsAuth, finish Authenticate / toggle / Logout first.

What if the tool list is empty?

One-line answer: Even with the server enabled, before auth completes Available Tools can be empty or the schema never arrives. Clear needsAuth first, then check tool allowlists and server-side failure.

How to split an empty list:

State	Meaning	Next step
Server = needsAuth, tools 0	No / expired session	Reconnect order above
Server = connected, tools 0	Handshake/schema fail or policy	MCP Logs + enterprise allowlist
Connected, tools present, call fails	Permission / remote API error	Logs for args and remote response

Checklist:

1. Confirm the server is enabled and needsAuth is cleared in Customize.
2. Check whether chat Available Tools regains that server’s prefixed tools. Docs: Cursor uses listed MCP tools when relevant.
3. If init succeeds but tools/list is empty, suspect the server process or remote endpoint—not auth.
4. On team/enterprise, Dashboard MCP Allowlist can block tools even when the config is visible.
5. If every other MCP is fine, blame that server’s OAuth/plugin, not Cursor globally.

If tools stay at zero after auth clears, you may fall through to connection-fail steps (toggle → remove → re-add). While needsAuth remains, remove-only loops often skip OAuth and reproduce the same symptom.

Frequently asked questions

How is this different from the connection-fail post?
Missing server or broken spawn → connection. Visible server with needsAuth / empty tools → this auth post.

Authenticate opens a browser and nothing else?
Check callback URL, popup blockers, and Cursor profile. Watch MCP Logs for callback/code receipt. Toggle off/on to restart the flow.

Where do I put tokens or pricing?
You don’t—in this post. Reconnect OAuth via the UI; if a key is required, put only the name in env / headers and keep the value local. No secrets or prices in the body.

Do stdio servers show needsAuth?
More often you see missing env keys or bad headers rejected by a remote API. The needsAuth UI is more common on OAuth remotes/plugins.

What should you remember?

needsAuth = auth axis; missing list / spawn fail = connection axis. Order: logs → Authenticate → toggle → Logout → (if needed) restart. Empty tools: clear needsAuth first, then allowlist and server logs.

Where are the official sources?

• Model Context Protocol (MCP) — OAuth, Static OAuth, logs, toggle FAQ
• Same page: How do I debug MCP server issues? — Output → MCP Logs
• Same page: Can I temporarily disable an MCP server? — Customize toggle