MCP connector
When it doesn't connect
Every way the Spera connector fails, what actually causes it, and the two-line fix — from 401s to "it can read but not write".
Updated 2026-08-26·Rev. 2026.06
Almost every failure is one of eight things. Find your symptom, then read that section.
| Symptom | Usual cause | Fix |
|---|---|---|
| No Spera tools appear at all | Added but never approved, or not restarted | Tools don't appear |
401, "unauthorized", "not authenticated" | No grant, or it expired or was revoked | 401 Unauthorized |
403 insufficient_scope | Read-only grant, or a grant from before a permission was added | 403 insufficient_scope |
| Reads fine, fails on the first save | Connected without ?mode=authoring | It can read but not write |
| "Authorization successful" but still broken | Grant arrived mid-session | Approved but still unauthorized |
| Local URL never connects | Connectors dial from the cloud | localhost doesn't work |
/mcp or /plugin "not found" | Those are terminal commands | Slash commands missing |
| Two Spera entries, one always dark | Two URLs are two separate grants | Two Spera entries |
Tools don't appear
The server is registered but was never authorized, or the client is still showing the tool list it cached before you approved.
- Confirm the entry exists in your client's MCP or Connectors settings.
- Approve the Spera sign-in if you have not.
- Fully quit and reopen the app — not just a new chat.
If there is still nothing, the entry may point at the wrong URL. Remove it and re-add using the exact URL from Connect your assistant.
401 Unauthorized
You have no valid grant. Either you never completed the sign-in, or the grant expired or was revoked.
Remove the Spera entry, add it again, complete the sign-in, and restart the app.
403 insufficient_scope, or "not allowed to do that"
This is a permissions answer, not a bug: the connection is valid, but the grant you hold does not include what was just attempted. Two causes.
You hold a read-only grant. The most common one — see the next section.
Your grant predates the permission. A grant records what existed when you approved it. If Spera added a permission afterwards, an older grant does not silently gain it. Reconnect and approve again, and the new list applies.
It can read but not write
Your assistant lists your strategies happily, then fails the moment it tries to save.
Your grant is read-only. Spera now asks every new connection for the full authoring set, so this means one of two things: you approved an older connection that asked only to read, or your client explicitly requested read-only permissions. A grant never gains permissions on its own.
Fix: remove the Spera entry, re-add it with the full URL ending in ?mode=authoring, approve the
consent screen again, and restart the client.
Approved but still unauthorized
The browser said authorization succeeded. The conversation you are in still behaves as though it did not.
A grant obtained partway through a running session does not attach to that session. The running client is still holding its unauthenticated connection.
Fix: quit the app completely and reopen it. A new chat in the same running app is usually not enough — the connection, not the conversation, is what needs to be re-established.
localhost doesn't work as a connector
You added http://localhost:3000/mcp on claude.ai or Claude Desktop and it never connects.
A connector is dialled from Anthropic's servers, not from your computer. localhost
there means their machine, where nothing is listening. This can never work, and no amount of
retrying will change it.
Local URLs are only usable by clients running on your own machine — Claude Code, Cursor, or VS Code. For everything else, use the hosted URL.
/mcp or /plugin doesn't exist in my app
Those are Claude Code terminal commands. They are not present in the Claude desktop app.
- Desktop / claude.ai: use Settings → Connectors.
- Anywhere with a shell:
claude mcp login spera,claude plugin …— these work regardless of which client you normally use.
Two Spera entries, and only one works
You have Spera registered twice — often once pointing at the hosted URL and once at a local one — and authorizing one leaves the other showing as unauthenticated.
Two different URLs are two separate things to authorize. One grant does not cover both, even though both are labelled "Spera". Clients report this confusingly: "authentication successful" and "not connected" at the same time.
Fix: keep one. Remove the entry you are not using, then approve the one you kept.
Still stuck
Note which client you are using, the exact URL in its settings, and the exact error text, then get in touch. Those three facts identify nearly every remaining case.