# Chess Goat authentication for agents

Public MCP tools (goat_card, game_history, favorite_openings, the free lessons, show_position) need no credentials. Goat Pass lessons, course progress and a purchased Goat Report need the user's own connection, over OAuth 2.1 (MCP authorization).

## Discover

- Call a protected tool, or send a request with an invalid token to https://trychessgoat.com/mcp: the 401 carries `WWW-Authenticate: Bearer resource_metadata="https://trychessgoat.com/.well-known/oauth-protected-resource/mcp"`.
- Protected resource metadata (RFC 9728): https://trychessgoat.com/.well-known/oauth-protected-resource
- Authorization server metadata (RFC 8414): https://trychessgoat.com/.well-known/oauth-authorization-server

## Pick a method

OAuth 2.1 authorization code with PKCE (S256), public clients (`token_endpoint_auth_method: none`). There are no API keys, client secrets or agent_auth / identity_assertion (ID-JAG) flows.

## Register

Dynamic client registration (RFC 7591): POST your `redirect_uris` to https://trychessgoat.com/oauth/register. Client ID metadata documents are also accepted.

## Claim

Send the user to https://trychessgoat.com/oauth/authorize with `response_type=code`, `code_challenge`, `resource=https://trychessgoat.com/mcp` and the scope from the metadata. The user signs in on Chess Goat with the email they bought with (or their site session) and approves; their Goat Pass and reports are found automatically.

## Exchange

POST the code and `code_verifier` to https://trychessgoat.com/oauth/token (`grant_type=authorization_code`). Refresh with `grant_type=refresh_token`.

## Use the access_token

Send `Authorization: Bearer <access_token>` on every request to https://trychessgoat.com/mcp.

## Errors

- 401 `invalid_token` with the WWW-Authenticate challenge above: re-run the flow.
- A protected tool without a connection returns an error result pointing to the connection prompt.
- 429 from /oauth/authorize or /oauth/register: rate-limited, retry later.

## Revocation

POST the token to https://trychessgoat.com/oauth/revoke (RFC 7009). Users can also email hello@trychessgoat.com to delete their connections.

Never ask users for passwords, codes, tokens or private report links in chat.