MCP not connecting in Claude Desktop? Full troubleshooting guide

Short answer: Most failed MCP connections come from four things: the config file is in the wrong location, the client was not fully restarted, the URL is missing the username segment, or the API key was pasted with a trailing space. IntoCal's endpoint is https://api.intocal.com/mcp/{username} over streamable HTTP — it needs no local process and no npx wrapper.

Confirm the endpoint responds first

Before touching any client, check the server from a terminal. A healthy endpoint answers the MCP initialize handshake:

curl -s -X POST https://api.intocal.com/mcp/yourname \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"curl","version":"1"}}}'

A JSON-RPC result means the server is fine and the problem is client-side. A 404 means the username is wrong — it is your IntoCal handle, the same one in intocal.com/u/yourname, not your email.

Claude Desktop

1. Settings → Connectors → Add custom connector.
2. Paste the URL above with your username.
3. Add your key as a Bearer token only if you want owner mode (auto-confirmed bookings, cancel, list).
4. Quit Claude completely — closing the window is not enough on macOS; use Cmd+Q, or quit from the menu bar icon on Windows.
5. Reopen and check the tools icon: list_event_types, query_slots, and request_booking should appear.

Cursor, Windsurf, and ChatGPT

• Cursor: Settings → MCP → Add new server, type "streamable http", same URL. Config lives at ~/.cursor/mcp.json.
• Windsurf: Settings → Cascade → MCP servers. Restart Cascade, not just the editor pane.
• ChatGPT: Settings → Connectors → Add connector (available on plans with connector support). Use the same URL; public mode works without a key.

Troubleshooting table

Public mode vs owner mode

Without a key, anyone's agent can read your open slots and request a booking — the booking is held pending until the guest confirms by email, so the endpoint is safe to publish. With an owner key, bookings confirm instantly and the cancel, list-bookings, and team-member tools unlock. Rotate keys any time in Dashboard → MCP; rotation takes effect immediately and old keys stop working on the next call.