# White Shoe MCP authentication

White Shoe exposes an OAuth-protected Model Context Protocol server for users of the White Shoe legal workspace.

This document describes the OAuth client connection flow that is live today. Dynamic client registration registers an OAuth client application; it does not register an autonomous agent identity.

## Service endpoints

- MCP Streamable HTTP endpoint: https://app.white-shoe.ai/api/mcp
- MCP Server Card: https://app.white-shoe.ai/api/mcp/server-card
- Protected Resource Metadata: https://app.white-shoe.ai/.well-known/oauth-protected-resource/api/mcp
- OAuth Authorization Server Metadata: https://app.white-shoe.ai/.well-known/oauth-authorization-server
- Dynamic Client Registration: https://app.white-shoe.ai/api/mcp/oauth/register
- Authorization endpoint: https://app.white-shoe.ai/api/mcp/oauth/authorize
- Token endpoint: https://app.white-shoe.ai/api/mcp/oauth/token
- Human-readable setup guide: https://app.white-shoe.ai/mcp

## Supported OAuth flow

Use the OAuth authorization-code grant with PKCE using the S256 challenge method. Include the exact resource indicator `https://app.white-shoe.ai/api/mcp` in both authorization and token requests.

Supported scopes:

- `mcp.read` — read the authenticated user's permitted workspace resources
- `mcp.write` — perform user-authorized workspace writes
- `mcp.jobs` — start, inspect, or cancel permitted background jobs

Request only the scopes needed for the user's task.

## Register an OAuth client

Send JSON to `POST https://app.white-shoe.ai/api/mcp/oauth/register`:

```json
{
  "client_name": "Your MCP client",
  "redirect_uris": ["http://127.0.0.1:49152/oauth/callback"],
  "software_id": "optional-stable-software-id",
  "software_version": "optional-version"
}
```

Redirect URIs must use HTTPS, a publisher-controlled reverse-domain private-use URI scheme for a native client (for example, `com.example.desktop:/oauth/callback`), or plaintext HTTP on an explicit loopback host (`localhost`, `127.0.0.1`, or `[::1]`). Native clients should prefer the loopback IP literals; `localhost` remains supported for compatibility with current MCP client metadata. White Shoe also accepts the supported-client compatibility schemes `claude:` and `chatgpt:`. URI fragments, embedded credentials, public HTTP hosts, arbitrary single-label schemes, and non-private schemes such as `file:`, `data:`, or `javascript:` are rejected. The authorization request's redirect URI must exactly match a registered value.

The registration endpoint issues a public `client_id`; no client secret is issued. Registration is distributed-rate-limited. Clients should persist and reuse the issued identifier instead of registering for every request. Registrations that remain unused for 30 days may expire.

## Authorize and exchange

1. Generate a PKCE verifier and its S256 challenge, plus a high-entropy `state` value.
2. Open `https://app.white-shoe.ai/api/mcp/oauth/authorize` in the user's browser with `response_type=code`, `client_id`, the exact registered `redirect_uri`, `code_challenge`, `code_challenge_method=S256`, requested `scope`, `state`, and `resource=https://app.white-shoe.ai/api/mcp`.
3. The user signs in, selects an authorized workspace, and approves access.
4. Verify the returned `state` exactly.
5. Exchange the one-time code at `https://app.white-shoe.ai/api/mcp/oauth/token` using form encoding with `grant_type=authorization_code`, `code`, `client_id`, `redirect_uri`, `code_verifier`, and `resource=https://app.white-shoe.ai/api/mcp`.
6. Send the access token only to https://app.white-shoe.ai/api/mcp in the `Authorization: Bearer` header.
7. When needed, rotate the refresh token at the token endpoint with `grant_type=refresh_token`, `refresh_token`, `client_id`, and the same `resource` value. Replace the prior refresh token with the newly returned token.

## Identity and protocol boundaries

White Shoe's MCP authorization server does not currently implement OpenID Connect and does not issue ID tokens. It also does not implement the WorkOS auth.md agent-identity profile: there is no `agent_auth` metadata block, ID-JAG exchange, anonymous-agent claim ceremony, or agent revocation-event endpoint. OAuth client registration must not be represented as support for those identity protocols.

White Shoe does not currently expose an A2A transport or A2A Agent Card. MCP discovery does not imply A2A support.