# Calorie Cub auth.md

Calorie Cub lets AI agents read and write a person's food diary on their behalf. Every agent acts for one signed-in person who approves it; there are no anonymous or agent-only accounts.

This file covers authentication. For each tool's purpose, Free and Pro limits, connecting and disconnecting, and errors, see the connector documentation: https://caloriecub.com/calorie-tracker-mcp-server

## Resources

- MCP server: `https://mcp.caloriecub.com/mcp` (Streamable HTTP, stateless). Unauthenticated calls return 401 with `WWW-Authenticate: Bearer resource_metadata="https://mcp.caloriecub.com/.well-known/oauth-protected-resource/mcp"`.
- REST API under `https://caloriecub.com/api/` (personal API keys only, see below).
- Protected resource metadata: `https://mcp.caloriecub.com/.well-known/oauth-protected-resource/mcp`
- Authorization server: issuer `https://caloriecub.com/api/auth`, metadata at `https://caloriecub.com/.well-known/oauth-authorization-server/api/auth`

## Register a client

OAuth 2.0 Dynamic Client Registration (RFC 7591), open, no initial access token:

`POST https://caloriecub.com/api/auth/oauth2/register` with `client_name`, `redirect_uris`, and `token_endpoint_auth_method: "none"` for public clients.

## Get a token

1. Authorization code with PKCE (S256): send the person to `https://caloriecub.com/api/auth/oauth2/authorize` with your `client_id`, `redirect_uri`, `scope`, `code_challenge`, and `resource=https://mcp.caloriecub.com/mcp`. They sign in and approve the scopes once.
2. Exchange the code at `https://caloriecub.com/api/auth/oauth2/token`. Ask for `offline_access` to get a refresh token.
3. Call the MCP server with `Authorization: Bearer <access_token>`.

Scopes: `diary:read`, `diary:write`, `library:write`, `goals:write`, plus `openid` and `offline_access`.

## Personal API keys

For clients without OAuth: the person creates a key in Settings → API keys (`cc_` followed by 64 hex characters) and gives it to the agent. Send it as `Authorization: Bearer cc_…` to the MCP server or the REST API. A read key can only read.

## Limits and revocation

- Tool calls and API-key requests count against a daily quota that resets at 00:00 UTC; `daily_limit_reached` means stop until then.
- The person can disconnect an app or revoke a key in Settings at any time; it takes effect immediately. Clients can revoke tokens at `https://caloriecub.com/api/auth/oauth2/revoke`.