# Tanjiren MCP Authentication

Tanjiren MCP uses hosted OAuth 2.1 with PKCE and Dynamic Client Registration.

## Discovery

An MCP client should start from the MCP server URL and discover auth metadata through:

- `/.well-known/oauth-protected-resource`
- `/.well-known/oauth-authorization-server`

The MCP endpoint responds with `401` and `WWW-Authenticate: Bearer resource_metadata=...` before authentication.

## Registration

Clients register through Dynamic Client Registration:

- `POST /api/mcp/register`

Redirect URI policy:

- `https` redirects are accepted generally
- `http` redirects are accepted only for loopback / localhost flows
- localhost callbacks support loopback port flexibility for native-style clients

## Authorization

Authorization uses:

- OAuth authorization code flow
- PKCE with `S256`

The resulting access token is:

- user-bound
- org-bound
- scope-bound
- short-lived

The token exchange also returns a refresh token. Refresh tokens are:

- opaque
- client-bound
- persisted server-side as hashes
- rotated on each use

Refresh token reuse is treated as replay and revokes the token family.

## Scope model

Main scopes:

- `mcp:read`
- `mcp:operate`
- `mcp:governance:read`

The server clamps requested scopes by org role:

- viewer: `mcp:read`
- member: `mcp:read`, `mcp:operate`
- admin/owner: `mcp:read`, `mcp:operate`, `mcp:governance:read`

Personal organizations do not receive governance reads.

## Security notes

- Authorization codes are one-time-use.
- Tokens are purpose-built for MCP, not browser cookies or pass-through identity tokens.
- Refresh tokens are rotated and replay-checked.
- Tool calls, resource reads, and prompt renders are audited.
- Operate actions still obey plan and org policy constraints.