MCP OAuth troubleshooting

For humans and autonomous agents connecting to https://legate.studio/mcp.

Store client_id with your tokens

After POST /oauth/register, persist the returned client_id alongside refresh_token and access_token. Every token request must send the same client_id that was used when the refresh token was issued.

Re-register only on invalid_client

Do not call /oauth/register on every refresh or after invalid_grant. Repeated registration creates orphan clients and breaks refresh binding. Register again only when the authorization server returns invalid_client (unknown client_id).

Access tokens last one hour

Access tokens expire after 3600 seconds. When MCP calls return HTTP 401, refresh with grant_type=refresh_token before retrying tools — do not start a new browser login unless refresh fails with an unrecoverable error.

Native / hosted agents: paste-code callback

If your redirect URI is https://legate.studio/oauth/native-callback, the user may need to paste the full callback URL (including code and state) back into the agent. Exchange the code promptly; authorization codes expire in 10 minutes.

Encryption v2 unlock at consent

Accounts with passkey encryption must unlock on the consent screen (Approve prompts for a passkey on the user's own browser) before Legate can issue tokens.

Agents must never ask the user to pair or approve an agent-operated browser (headless, remote, or in-app webview) as a new device. That would hand the user's data encryption key to a browser the agent controls. Instead:

• Send the user the /oauth/authorize link to open on their own phone or computer, or
• Use the https://legate.studio/oauth/native-callback paste-code flow so the user completes authorization on their device and pastes the callback URL back to the agent.

OAuth access_denied responses that mention encryption unlock include the same guidance in error_description.

Discovery

• Authorization server metadata: /.well-known/oauth-authorization-server
• Protected resource (MCP): /.well-known/oauth-protected-resource/mcp
• Setup guide: /docs/mcp