Skip to main content
Spyro AI runs its own OAuth 2.1 authorization server for MCP. Compliant MCP clients do this automatically from the server address alone. Read this page if you build a client, an app directory listing or a custom integration.
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:
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:// on localhost, 127.0.0.1 or [::1], with any port.
  • The one custom scheme cursor://anysphere.cursor-mcp/oauth/callback.
An invalid client or redirect URI never redirects. The user sees an error page instead. Unverified clients cannot use a name containing “Spyro”.

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 free listWorkspaces 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.

Limits to design around

Common errors