When an MCP server won't connect in Cursor, check the boring layers before you touch OAuth: which `mcp.json` file holds the entry, whether the entry matches the transport, whether a local command can actually start, and whether the environment variables it needs resolve. Only after that is it worth looking at the auth layer: client registration and the redirect URL. Cursor's docs say its MCP logs show "connection errors, authentication issues, or server crashes," so read them before each change. Restart the client so it re-reads the MCP config after every edit.
Who this is for
You added a server to Cursor, it doesn't connect, and you're about to rewrite your OAuth code. Run these in order first.
The 7 checks
| # | Check | What Cursor's docs say | Go deeper |
|---|---|---|---|
| 1 | Right file | Project config lives in `.cursor/mcp.json`; global config in `~/.cursor/mcp.json`. | — |
| 2 | Entry matches transport | `stdio` servers take a shell command; SSE and Streamable HTTP servers take a URL. Remote entries use `url`. | MCP OAuth for Cursor and Claude |
| 3 | Command can start | A stdio `command` "Must be available on your system path or contain its full path." | — |
| 4 | Env vars resolve | `envFile` is stdio-only. Remote servers don't support it; use `${env:NAME}` interpolation with variables set in your shell profile or system environment. | — |
| 5 | Read the logs | MCP logs show "server initialization, tool calls, and error messages." | MCP Inspector OAuth debugging |
| 6 | Client registration | For providers without Dynamic Client Registration, or with a fixed Client ID, add an `auth` object with `CLIENT_ID` (required), optional `CLIENT_SECRET` and `scopes`. | Static client ID in mcp.json · When you need DCR |
| 7 | Redirect URL registered | Cursor uses fixed callbacks: `https://www.cursor.com/agents/mcp/oauth/callback` (web and Cursor Agents) and `http://localhost:8787/callback` (desktop). Register both if users sign in from both. | Cursor OAuth redirect URI |
Checks 1–5 are config and transport. Checks 6–7 are auth. If 1–5 fail, no amount of OAuth work will help.
Pitfalls
- Editing the wrong file. Cursor has a project file and a global file. Confirm which one you changed.
- Expecting `envFile` on a remote server. It only works for stdio. Remote entries need interpolated environment variables.
- Hardcoding secrets. Cursor's docs say to use environment variables for Client ID and Client Secret instead of hardcoding them.
- Treating a 401 as a connect failure. If the server answers 401, transport works and you're in the auth layer. Read the failure card and WWW-Authenticate and protected resource metadata in plain English before you change code.
- Omitting scopes without knowing the fallback. If `scopes` is omitted, Cursor uses `/.well-known/oauth-authorization-server` to discover `scopes_supported`, so that endpoint has to answer.
How to check it
- Open the `mcp.json` you edited and confirm the server name, `command` or `url`, and env references.
- For stdio, run the same command in a terminal from the project root.
- Restart the client so it re-reads the MCP config.
- Read the MCP logs for the first error and fix only that.
- If the error is auth-related, move to checks 6 and 7 and the linked posts.
Where ShipKits fits
If you're building your own MCP server and want working servers to start from, the MCP Starter Kit ($27) is five Python FastMCP servers plus client-examples/claude-desktop-config.json. Connect Claude Desktop (and any MCP-compatible client, including Cursor) with the same python command, for example `python servers/filesystem/server.py`. If you only need to debug someone else's server, the checks above and the free templates at /free are enough. Cheat Sheet for the skim checklist mindset.
Soft next step
Run checks 1–5 now, before you open your auth code. For free templates, start at /free. When you want ready-made servers to connect and test against, the MCP Starter Kit ($27) has five.