Use a key for scripts and servers. Use OAuth for apps that act on behalf of a person, so no secret is stored in a file.
How a client finds everything
1
Call the endpoint without a credential
POST https://mcp.spyro.app/mcp returns 401 with a header like:2
Read the protected resource metadata
GET https://mcp.spyro.app/.well-known/oauth-protected-resource/mcp (RFC 9728) returns the resource, the authorization server, and scopes_supported: spyro.read and spyro.actions.3
Read the authorization server metadata
GET https://mcp.spyro.app/.well-known/oauth-authorization-server (RFC 8414) lists the endpoints below.
The sign-in page is on the main
spyro.app host, and the token, registration and revocation endpoints are on the issuer host mcp.spyro.app. These endpoints answer CORS with * and send no-store.
Register a client
Pick one of three ways:- Client ID metadata document
- Dynamic registration
- Manual client
Use an
https URL you host as your client_id. Spyro AI fetches it (5 second timeout, 64 KB limit) to read your name and redirect URIs. Verified vendors such as claude.ai, claude.com and chatgpt.com use this.Redirect URI rules
- Any
https://URI, matched exactly. http://onlocalhost,127.0.0.1or[::1], with any port.- The one custom scheme
cursor://anysphere.cursor-mcp/oauth/callback.
Authorization code flow
1
Send the user to the authorization endpoint
resource must be the MCP address. PKCE with S256 is required.2
The user approves
The user signs in, picks the workspaces, chooses Read or Read and take actions, sets a daily credit limit and clicks Allow. The granted scope can differ from what you asked for, so read it from the token response.
3
Receive the code
The user returns to your
redirect_uri with code, state and iss. Check state and iss. A code lives 60 seconds and works once. Reusing a code revokes the whole grant.4
Exchange the code
5
Call the MCP endpoint
Send
Authorization: Bearer spyro_at_... as you would with a key.Scopes
The 401 challenge asks for
spyro.read only. The user decides on the approval screen whether to raise or lower it.
Tokens
Refresh with
grant_type=refresh_token. For public clients the refresh token rotates: use the new one from each response. A retry within 60 seconds of the first use is tolerated and returns a fresh pair, but a later reuse revokes the grant. Confidential clients and Google-hosted clients keep the same refresh token.
Tokens, codes and secrets are stored only as hashes. To disconnect, POST /oauth/revoke with the token. It always returns 200 and revokes the whole grant.
Several workspaces
One approval can cover several workspaces. In that case the server adds a freelistWorkspaces tool, and every tool takes an optional workspace argument (the workspace id). Call listWorkspaces first and pass the id on later calls. If you omit it with several workspaces connected, the tool returns an error that lists the valid ids. Every call re-checks that the user is still a workspace admin, the plan includes MCP, billing is active and the scope allows the tool. For a signed-in connection, a plan or billing problem comes back as a tool error (MCP is not included in this workspace's plan. or This workspace's Spyro AI subscription is not active.), not as an HTTP 403.
