Connecting

The Spanly MCP server speaks HTTP MCP at https://mcp.spanly.com. Authentication uses OAuth: the first time a client connects, it opens a browser window where you sign in with your Spanly account. There is no API key to copy. The agent gets the same access you have.

Claude (Desktop and claude.ai)

Add Spanly as a custom connector:

1. Open Settings → Connectors → Add custom connector.
2. Enter https://mcp.spanly.com as the URL.
3. Complete the sign-in flow in the browser window that opens.

Claude Code

claude mcp add --transport http spanly https://mcp.spanly.com

Then run /mcp inside Claude Code and pick spanly to complete the sign-in flow.

Cursor

In .cursor/mcp.json (per project) or ~/.cursor/mcp.json (global):

{
  "mcpServers": {
    "spanly": {
      "url": "https://mcp.spanly.com"
    }
  }
}

Cursor detects that the server requires OAuth and prompts you to sign in on first use.

Windsurf

Same shape as Cursor: add the server URL to Windsurf's MCP settings and complete the sign-in prompt.

curl smoke test

The server requires an OAuth access token, so a bare request is rejected. That rejection is itself a useful connectivity check:

curl -i -X POST https://mcp.spanly.com/ \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"curl-test","version":"1.0.0"}}}'

A healthy server answers 401 with a WWW-Authenticate header that points at the OAuth metadata:

curl -s https://mcp.spanly.com/.well-known/oauth-protected-resource

If both respond, the server is reachable and any remaining issue is in your client's sign-in flow.

Authentication & scope

• Sign in with your Spanly account when the client prompts you.
• The agent's access mirrors yours: it sees the organisations and projects you can see in the dashboard.
• Tokens are issued and refreshed by the client. Revoke access from your account settings at any time.

Troubleshooting

• 401 Unauthorized: the client has no valid token. Re-run the client's sign-in flow (for Claude Code, /mcp → spanly → authenticate).
• Sign-in window never opens: some clients only support OAuth-protected MCP servers in recent versions. Update the client first.
• 406 Not Acceptable on curl: include -H "Accept: application/json, text/event-stream". The server streams responses as SSE frames.

If a tool call returns an error with a specific message, that's the backend speaking. Open the request in your dashboard to see the same error in human form.