# auth.md - signing in to Cloche

Cloche's MCP server is a protected resource. A client discovers how to sign in from
the server itself, so there is nothing here to configure by hand and nothing to copy
from this page into a settings screen.

## Discovery from the main site

- [Protected-resource metadata](https://cloche.dev/.well-known/oauth-protected-resource)
  redirects to the MCP server's canonical metadata document.
- [Authorization-server metadata](https://cloche.dev/.well-known/oauth-authorization-server)
  discovers the current issuer from that document and redirects to the issuer's
  own OAuth metadata.

These are discovery entrypoints. The protected resource remains
`https://mcp.cloche.dev/mcp`, and the issuer remains the authorization server named
in its metadata. Clients validate those identities using the canonical discovery
chain below. `https://cloche.dev` is neither the OAuth issuer nor the token audience.

Cloche supports browser-approved OAuth sign-in. This document does not advertise
the WorkOS auth.md agent-registration protocol: there is no `agent_auth`
registration or claim endpoint to call.

## The chain

1. Call `https://mcp.cloche.dev/mcp` with no token. Every method, `initialize`
   included, answers **401** with the challenge that starts the flow:

       WWW-Authenticate: Bearer resource_metadata="https://mcp.cloche.dev/.well-known/oauth-protected-resource"

2. Fetch that document. It is protected-resource metadata (RFC 9728) and it names
   this resource and its authorization server.
3. Fetch the authorization server's own metadata for the endpoints, the grant types
   and the scopes it supports. Cloche does not restate them here: the metadata is
   the truth and it changes without this page. The server is WorkOS AuthKit, so a
   sign-in page on their domain is expected rather than a redirect gone wrong.
4. Let your client run the authorization-code flow with PKCE that the metadata
   advertises. This is what a remote MCP client already does; the person completes
   it in their browser.
5. Once the client holds the token, call `list_apps`. A successful result, including
   an empty list, is the proof.

The 401 is deliberate and it is not a fault to report. A client that gets a 200 from
an unauthenticated `/mcp` concludes no sign-in is needed and then offers the person
no way in.

## Where the token may go

The access token's audience is `https://mcp.cloche.dev/mcp`. It is for that address
and no other. Never put it, a refresh token, a password or a sign-in code into the
conversation: the client holds credentials, the model does not.

## When sign-in does not finish

- **The tools do not appear.** Some clients freeze their tool list for the
  conversation. Say that a restart or a new conversation is needed, then verify with
  `list_apps` before claiming Cloche is ready.
- **A call fails after sign-in.** Report what Cloche said. The answer is written to
  be read out; do not translate it into a status code.

## The rest of the pack

- [AGENTS.md](./AGENTS.md): the facts and the procedure in one place.
- [The contract](https://cloche.dev/agent-setup/prompt.md): what Cloche asks of you.
- [The machine card](./.well-known/mcp/server-card.json): the same connection facts as JSON.