Connect a remote MCP server to Claude and Cursor, and what to check when it fails
Adding a remote MCP server to Claude or Cursor takes a minute. When it doesn't work, though, the error rarely says why. This guide covers both clients and the order to check things in when the connection fails.
We checked the steps against each vendor's documentation on 25 October 2026 and again on 6 November 2026. Both interfaces change often, so if a menu name differs from what you see, trust the vendor's page. Links are at the end.
Before you start: where the connection comes from
This is the difference that decides most failures.
- Claude connects from Anthropic's cloud, not from your computer. That holds in every Claude client, Claude Desktop included. Your server must be reachable over the public internet. A server on
localhost, behind a VPN or on a private network won't connect. If it sits behind a firewall, allow Anthropic's outbound ranges:160.79.104.0/21and153.61.208.0/20(IPv4) on 6 November 2026. The current list is on Anthropic's IP addresses page. - Cursor on your computer connects from your computer. Cursor's own example config points at
http://localhost:3000/mcp. A server that only your machine can reach works in Cursor but not in Claude. Cursor's Cloud Agents are the exception: they keep their sign-ins on Cursor's servers.
So "it works in Cursor" proves less than it seems. Before adding the server to Claude, check that it answers from outside your network.
Add it to Claude
On Free, Pro, Max and Ultra:
- Open Customize → Connectors.
- Click + Add, then Add custom connector.
- Enter a name and the server's URL, for example
https://your-server.example/mcp, and click Continue. - Claude shows the authentication it detected. Under Authentication, choose Sign in now, Sign in when needed or No sign in.
- If the server uses OAuth, pick an OAuth client: Claude's published identity (the recommended default), automatic registration, or your own client.
- If the server takes a fixed API key or bearer token instead, add it under Request headers.
- Click Add.
Free accounts can add one custom connector. On Team and Enterprise, an owner adds the connector under Organization settings → Connectors (Add → Custom → Web). Members then click Connect next to it in Customize → Connectors.
To use the server in a chat, click + at the lower left of the chat box, open Connectors, and switch it on for that conversation. To change a connector's URL or settings, remove it and add it again.
Add it to Cursor
Cursor reads MCP servers from a JSON file:
.cursor/mcp.jsonin a project, for that project only;~/.cursor/mcp.jsonin your home folder, for every project.
A remote server is a name with a url:
{
"mcpServers": {
"my-server": {
"url": "https://your-server.example/mcp"
}
}
}
If the server wants a fixed token, add headers. Keep the secret in an environment variable instead of the file:
{
"mcpServers": {
"my-server": {
"url": "https://your-server.example/mcp",
"headers": {
"Authorization": "Bearer ${env:MY_SERVER_TOKEN}"
}
}
}
}
Cursor supports OAuth for remote servers too, including dynamic client registration. For a provider without dynamic registration, you can give Cursor a fixed client ID in an auth object. Then switch the server on in Customize in the sidebar. To see what happened, open the Output panel (Cmd+Shift+U) and choose MCP Logs. It shows the handshake, tool calls and errors.
When it doesn't connect: check in this order
1. Is the URL right, and reachable from outside? Use the full endpoint path (/mcp, not just the domain). From a machine outside your network, or a phone hotspot, send the first request a client sends:
curl -sS -i https://your-server.example/mcp \
-H 'content-type: application/json' \
-H 'accept: application/json, text/event-stream' \
-H 'mcp-protocol-version: 2025-11-25' \
-d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-11-25","capabilities":{},"clientInfo":{"name":"connect-test","version":"1"}}}'
A working server answers with HTTP 200 and a JSON-RPC result naming its protocol version, or with 401 if it needs you to sign in. A timeout, a DNS error or an HTML page means a client won't get further than you did.
2. Does it ask for credentials, and how? A 401 should carry a WWW-Authenticate header that points to the server's protected resource metadata. That pointer is how a client finds where to send you to sign in. Without it, the client can only try the well-known metadata address. If that fails too, there is nothing to sign in to, and the fixed-header route is left, if the server offers one. Our guide to 401 responses and protected resource metadata has the curl commands for each step. On our probe's latest run of each tracked server from the past three days, 1,944 of 5,924 asked for credentials before they would list tools (read 25 October 2026, 19:51 UTC). So a sign-in step is normal, not a sign that something is broken.
3. Does it speak the current transport? Cursor accepts Streamable HTTP (a POST to the single endpoint above) and the older HTTP+SSE transport. Claude's help page doesn't name a transport. Streamable HTTP is the one in the current specification, so serve that. If your server still offers only an /sse endpoint, see moving from SSE to Streamable HTTP.
4. Does tools/list come back? If the client connects but shows no tools, the handshake worked and a later step didn't. How to test an MCP server before you ship it walks through the steps after the handshake with curl, one at a time.
5. Read the client's log, and re-add after a fix. In Cursor, the log is MCP Logs in the Output panel. In Claude, a connector can't be edited in place. After you change the server's URL or sign-in setup, remove the connector and add it again.
Check it from outside first
If you didn't write the server, or want an outside view before you debug your own setup, look it up on MCP Checkup. Our probe connects from the public internet without credentials, much as a cloud client would before you sign in. The report shows whether the server answered, which protocol revision it negotiated, whether it asked for credentials and how, and which tools it listed. It reports what we observed, not a judgement of the server.
Vendor documentation used, checked 25 October and 6 November 2026:
- Claude Help Center, "Getting started with custom connectors using remote MCP"
- Anthropic, "IP addresses" (platform.claude.com/docs/en/api/ip-addresses)
- Cursor Docs, "Model Context Protocol (MCP)" (cursor.com/docs/context/mcp)