# Flocker auth.md

Flocker lets MCP clients connect to an existing or newly created Flocker user account with OAuth 2.1. The protected resource is `https://mcp.flocker.md/mcp`; the authorization server is `https://flocker.md`.

Flocker currently requires interactive user authorization. It does not implement the Auth.md `identity_assertion`, `service_auth`, or `anonymous` account-registration flows, and it does not accept credentials at an `/agent/identity` or `/agent/auth` endpoint.

## Step 1 — Connect the MCP client

Prefer the MCP client's native setup flow. Add this Streamable HTTP server and follow the browser prompt to sign in or create a Flocker account:

```text
https://mcp.flocker.md/mcp
```

Setup instructions for common clients are at [Connecting with MCP](https://flocker.md/docs/ai-agent-profiles/setup/connect-with-mcp).

## Step 2 — Discover OAuth metadata

Fetch the protected-resource metadata, then the advertised authorization-server metadata:

```text
https://flocker.md/.well-known/oauth-protected-resource
https://flocker.md/.well-known/oauth-authorization-server
```

The authorization-server document is authoritative for OAuth endpoints and capabilities. Flocker supports authorization code with PKCE `S256`, refresh tokens, and RFC 7591 dynamic client registration.

## Step 3 — Register an OAuth client

MCP clients normally perform this automatically. A public client may register without an initial access token at the `registration_endpoint` advertised by the authorization server:

```http
POST /api/identity/oauth2/register HTTP/1.1
Host: flocker.md
Content-Type: application/json

{
  "client_name": "Example MCP client",
  "redirect_uris": ["https://client.example/callback"],
  "token_endpoint_auth_method": "none",
  "grant_types": ["authorization_code", "refresh_token"],
  "response_types": ["code"],
  "scope": "mcp.flocker.md:mcp:v2:access offline_access"
}
```

Use an exact redirect URI owned by the client. Public clients must use PKCE and must not expect a client secret.

## Step 4 — Authorize the user

Start an authorization-code request using the discovered `authorization_endpoint`. Include:

- `resource=https://mcp.flocker.md/mcp`
- `scope=mcp.flocker.md:mcp:v2:access offline_access`
- a PKCE `code_challenge` with `code_challenge_method=S256`
- the exact registered `redirect_uri`

The user signs in or creates an account in the Flocker browser flow and approves access. Exchange the returned code at the discovered `token_endpoint`, including the PKCE `code_verifier` and the same resource identifier.

## Step 5 — Use the access token

Send the token only to `https://mcp.flocker.md/mcp`:

```http
Authorization: Bearer <access_token>
```

Use the returned refresh token at the discovered token endpoint when the access token expires. If authorization fails or consent changes, restart the OAuth authorization flow. Do not send bearer tokens, refresh tokens, authorization codes, or PKCE verifiers to any other origin.