# Habits

> Habit tracker with a hosted API and MCP server so any AI agent can read and update a person's habits for them. Bearer API keys (email-code sign-in) or OAuth on the MCP endpoint.

- Agent mode homepage: https://habits.kevnk.com/
- Rules for agents: https://habits.kevnk.com/guide.md
- Tool catalogue with JSON schemas: https://habits.kevnk.com/api/tools
- MCP endpoint: https://habits.kevnk.com/mcp
- OAuth protected-resource metadata: https://habits.kevnk.com/.well-known/oauth-protected-resource
- Capabilities manifest: https://habits.kevnk.com/.well-known/agent.json
- Source, CLI, skill: https://github.com/kevnk/habits-app

## Endpoints (one line each; schemas at /api/tools)
- POST /api/auth/request-code {email} → email a six-digit code
- POST /api/auth/verify-code {email, code, name?, timezone?} → {apiKey, user, created}
- GET /api/me → user, keys; PATCH /api/me {timezone}
- GET /api/me/keys; POST /api/me/keys {name} → {apiKey}; DELETE /api/me/keys/{id}
- GET /api/tools → catalogue; POST /api/tools/{name} {args} → result
- GET /api/sync?since=N; POST /api/sync {workspaces, habits, marks}
- POST /mcp → MCP Streamable HTTP

## Error recovery
- Errors are JSON: error.code, error.message, error.hint, plus lists such as available or candidates.
- 401 unauthorized: get or reload an API key. 429 rate_limited: wait retryAfter seconds.
- habit_not_found / workspace_not_found: pick from `available`. ambiguous_*: use the id from `candidates`.
- date_in_future / invalid_date: dates are YYYY-MM-DD in the user's timezone.