# auth.md for Hormi

Hormi (https://hormi.app) exposes a Model Context Protocol (MCP) server at https://api.hormi.app/mcp.
Access is granted per user through OAuth 2.1. There are no API keys.
Human documentation: https://hormi.app/docs/mcp

## Who can connect

Any MCP client acting on behalf of a Hormi user. The user's household must
have Hormi Plus or an active trial; otherwise authorization is refused with an
explanation and a link to activate the plan.

## Steps

1. Discover. Call https://api.hormi.app/mcp without credentials. The 401 response carries
   `WWW-Authenticate: Bearer resource_metadata="..."`. That document
   (https://api.hormi.app/.well-known/oauth-protected-resource) names the authorization
   server and the permissions it supports. The authorization server metadata
   (https://api.hormi.app/.well-known/oauth-authorization-server) lists the registration,
   authorization, token and revocation endpoints.
2. Register. Use dynamic client registration at the registration endpoint.
   Public clients declare `token_endpoint_auth_method: "none"`. Redirect URIs
   must be https, loopback http://127.0.0.1 (any port) or a reverse-domain
   custom scheme.
3. Authorize. Open the authorization endpoint in the user's browser with the
   authorization-code flow and PKCE (S256), including `resource=https://api.hormi.app/mcp`.
   The user signs in to Hormi and approves the requested permissions on a
   consent screen. Omitting `scope` requests every permission.
4. Exchange. Trade the code for tokens at the token endpoint. Access tokens
   last one hour. Refresh tokens last 30 days and rotate on every use.
5. Use. Send `Authorization: Bearer <access token>` to https://api.hormi.app/mcp
   (Streamable HTTP, POST). Tokens work only on the MCP endpoint.
6. Refresh and revoke. Refresh at the token endpoint; revoke at the
   revocation endpoint. Users can also disconnect from their assistant.

## Permissions

profile:read, expenses:read, expenses:write, incomes:read, incomes:write,
categories:read, categories:write, households:read, reports:read.
Write permissions cover creating, editing and deleting the user's own records.
Nothing can change the subscription, the members or the household itself.

## Support

support@hormi.app