# auth.md

Kinjay supports agents that act for a person on their own household health records. The remote MCP server is https://mcp.kinjay.com/mcp. Private records require OAuth and explicit approval by the Kinjay account owner in a browser. The user may simply ask their agent: Connect to Kinjay. Public entry point: https://kinjay.com/#agents

## Discover

1. Send an unauthenticated request to https://mcp.kinjay.com/mcp. The 401 response carries a `WWW-Authenticate: Bearer resource_metadata="..."` header.
2. Fetch the protected-resource metadata at https://mcp.kinjay.com/.well-known/oauth-protected-resource/mcp. It is authoritative for `resource` and `authorization_servers`.
3. Fetch the authorization server's metadata from the advertised issuer. Supabase Auth is the authorization server; use its advertised endpoints.

The homepage api-catalog Link relation and https://kinjay.com/llms.txt lead to the same metadata.

## Pick a method

Kinjay supports one method: the OAuth 2.1 authorization-code flow with PKCE, completed by the user in a browser. Kinjay does not offer API keys, service accounts, or the identity_assertion, service_auth, or anonymous agent registration methods. If the agent cannot configure a remote Streamable HTTP MCP server or complete a browser OAuth flow, tell the user which capability is missing.

## Register

Use the agent's own OAuth client, registered with the authorization server as its metadata advertises. Do not reuse another agent's client ID.

## Authorize

1. Start the authorization-code flow with PKCE. Request the scopes listed in the metadata's `scopes_supported` (`openid`; Kinjay enforces no scopes) and the resource https://mcp.kinjay.com/mcp at authorization and token exchange.
2. Open the browser sign-in and consent prompt. The account owner confirms the connection. The client can access the owner's household people and records, including people added later, through the supported tools. Available tools read household/person profiles, create people after explicit user approval and a person-authority attestation, read records, add readings/documents, conditions, allergies, history events, appointments, immunisations, care notes, doctors/clinics, insurance policies and household directory contacts, run Kinjay's AI reading on a saved original, save a reviewed report's results after the user's explicit confirmation, give time-limited original download links, and add medication and supplement records. Medication/supplement editing and deletion are unavailable through agents; use the Kinjay website for those changes. There is no read-only or per-person grant. An OAuth identity scope alone does not grant a Kinjay health record.
3. Exchange the authorization code at the token endpoint.

## Use the access_token

- Send the access token as `Authorization: Bearer <token>` to https://mcp.kinjay.com/mcp over Streamable HTTP. Direct cross-origin browser clients are not supported.
- Verify tool discovery and list_people before claiming connection success. Ask which returned person the user means before reading that person's records.
- Use source IDs and get_record_source to attribute record facts to their original source, and carry those references into summaries. Add records only when the user requests them, with the user's supplied values. Agents cannot edit or delete medications/supplements, care records or contacts, change contact favourites, or relabel saved documents. Report-derived results stay pending until the user has checked every row against the original and explicitly confirmed them. Never present an uncited clinical conclusion as Kinjay's own.
- List tools return items, has_more and next_cursor. Follow both cursor fields with unchanged filters/order. list_records can filter analyte_name, vital_type and recorded/entry dates; sort_by=recorded_at orders by the recorded date rather than entry time. Missing recorded dates are excluded from recorded-date sorting/filtering. Timestamp date bounds use UTC days. The overview explicitly lists its included/excluded categories and is never a complete history.
- Tools return recorded facts and source references, not medical advice. Original documents remain private; a download link from get_document_original works for anyone holding it for one hour, so share it only with the user.
- Send tokens only in authenticated protocol requests. Never put credentials in chat, tool content, logs, or public URLs, and never ask the user for a password or token in chat.

## Errors

| Status | Meaning | Action |
| --- | --- | --- |
| 401 Authentication required | Missing, invalid, or expired token | Refresh the token or restart the authorization flow from Discover |
| 403 Connection unavailable | The connection was disconnected or is not active | Ask the user to reconnect through the browser flow |
| 403 Origin unavailable | Cross-origin browser request | Connect from a server-side MCP client |

## Revocation

The user can disconnect an agent at https://kinjay.com/connections (sign-in required). Disconnecting stops future Kinjay access; it cannot recall information an agent provider has already received or retained.

Terms: https://kinjay.com/terms
Privacy: https://kinjay.com/privacy
Consumer health data: https://kinjay.com/consumer-health-data-privacy
Support: support@kinjay.com