Connect your assistant

You need a free Spera account first — the connector works in your account, so there is nothing to connect to until you have one.

The fastest path is the picker on spera.bot/mcp, which shows only the app you chose. If you would rather do it by hand, pick your app below.

https://api.spera.bot/mcp?mode=authoring

Cursor

Use Install in Cursor on spera.bot/mcp?client=cursor. Approve the Spera sign-in when it opens, then fully quit and reopen Cursor.

If the button appears to do nothing, the cursor:// scheme is not registered on your machine or your browser dropped it. Run this instead — it writes to your user profile, so Spera is available in every window:

cursor --add-mcp '{"name":"spera","type":"http","url":"https://api.spera.bot/mcp?mode=authoring"}'

Then ask: What Spera projects do I have?

Claude Desktop and claude.ai

Claude cannot be prefilled — the Add custom connector dialog is empty until Spera is in Anthropic’s directory.

1. Copy the URL above (the Open Claude button on spera.bot/mcp?client=claude copies it for you).
2. Open Settings → Connectors (in Claude Desktop: Customize → Connectors).
3. Choose Add custom connector, paste the URL, and confirm.
4. Sign in to Spera and approve the permissions.
5. Quit and reopen Claude.

A localhost URL never works here. Claude Desktop and claude.ai dial from Anthropic’s servers, not your machine.

VS Code

Use Install in VS Code on spera.bot/mcp?client=vscode. Approve the sign-in, then reload the window.

The install link opens VS Code Stable. On Insiders, or if the link does nothing, use the CLI — swap code for code-insiders:

code --add-mcp '{"name":"spera","type":"http","url":"https://api.spera.bot/mcp?mode=authoring"}'

Claude Code

One command, in any terminal:

Copy both lines and paste them into any terminal at once — they run in order:

claude mcp add --transport http --scope user spera "https://api.spera.bot/mcp?mode=authoring"
claude mcp login spera

Approve the sign-in in the browser tab that opens, then restart Claude Code.

The same connection without a repo checkout can also install the eight guided workflows as skills: /plugin marketplace add praveenmanikandan/spera-cursor-plugin, then /plugin install spera@spera. The command above is enough to connect.

Codex

Copy both lines and paste them into any terminal at once. The second is not optional — Codex does not prompt for sign-in, so without it you get a registered but unauthenticated server:

codex mcp add spera --url "https://api.spera.bot/mcp?mode=authoring"
codex mcp login spera

Then fully quit and reopen Codex.

Gemini CLI

gemini mcp add --transport http spera "https://api.spera.bot/mcp?mode=authoring"

Windsurf

Merge this into ~/.codeium/windsurf/mcp_config.json, then reload Windsurf:

{
"mcpServers": {
  "spera": {
    "type": "streamable-http",
    "serverUrl": "https://api.spera.bot/mcp?mode=authoring"
  }
}
}

Any other MCP client

Register the URL above as a streamable HTTP MCP server. Spera implements standard OAuth discovery and dynamic client registration, so a compliant client needs no API key, no manual client ID, and no configuration beyond the URL.

This includes clients whose settings only accept a plain URL with no custom headers — Zed, JetBrains, Cline, Continue. Because Spera carries the authoring mode in the URL rather than in an HTTP header, those clients still get full authoring access. That is the reason the published URL looks the way it does.

Restart after approving — this is not optional

Approving the connection creates a grant. A grant obtained partway through a running session does not attach to that session. The client will often report success while the conversation you are in still behaves as unauthenticated.

Fully quit and reopen the app after approving. This one step accounts for most "it said it worked but nothing happened" reports.

Why the mode query matters

Spera asks for the smallest set of permissions a client actually needs. A plain request gets two read permissions. Requesting the ten authoring permissions takes an explicit signal, and there are two ways to send it: an HTTP header, or ?mode=authoring on the URL.

Connector interfaces — the ones with a paste-a-URL box — cannot set custom HTTP headers. So for those clients the query string is the only way to ask, which is why it is the form we publish everywhere.

The query string is not part of the identity Spera authorizes against. Both forms resolve to the same resource and the same single grant, so nothing gets authorized twice and there is no downside to always using the longer URL.

Next

• What you're approving
• What to ask for
• When it doesn't connect