# Recipe Logger — Agent Authentication

Recipe Logger uses **OAuth 2.1** for AI agent access to the hosted MCP server.

## Discovery

1. **Protected Resource Metadata (RFC 9728):** `https://recipelogger.com/.well-known/oauth-protected-resource`
2. **Authorization Server Metadata (RFC 8414):** `https://recipelogger.com/.well-known/oauth-authorization-server`
3. **OIDC Discovery:** `https://recipelogger.com/.well-known/openid-configuration`
4. **MCP Server Card:** `https://recipelogger.com/.well-known/mcp/server-card.json`

## MCP Endpoints

- **Recommended (ChatGPT):** `https://recipelogger.com/mcp`
- **Versioned API path:** `https://recipelogger.com/api/v1/mcp`

Both endpoints accept `POST` with JSON-RPC 2.0 and require `Authorization: Bearer <access_token>`.

## Registration

Agents may register using one of:

- **Dynamic Client Registration (DCR):** `POST https://recipelogger.com/api/v1/auth/oauth2/register`
- **Client ID Metadata Documents (CIMD):** supported when `client_id_metadata_document_supported` is `true` in authorization-server metadata.

## Authorization Flow

1. Discover endpoints from `/.well-known/oauth-authorization-server`.
2. Start authorization at `https://recipelogger.com/api/v1/auth/oauth2/authorize` with PKCE.
3. User signs in and consents to requested scopes.
4. Exchange the authorization code at `https://recipelogger.com/api/v1/auth/oauth2/token`.
5. Call MCP with the access token.

## Supported Scopes

| Scope | Access |
|-------|--------|
| `openid`, `profile`, `email`, `offline_access` | Standard OIDC |
| `recipes:read` | List and read recipes |
| `recipes:write` | Create, update, delete recipes |
| `shopping:read` | List and read shopping lists |
| `shopping:write` | Manage shopping lists |
| `mealplans:read` | List and read meal plans |
| `mealplans:write` | Manage meal plans |
| `stores:read` | List stores and store layouts |

## Token Usage

Include the access token on every MCP request:

```http
POST https://recipelogger.com/mcp HTTP/1.1
Authorization: Bearer <access_token>
Content-Type: application/json

{"jsonrpc":"2.0","id":1,"method":"tools/list"}
```

On `401 Unauthorized`, follow the `WWW-Authenticate` header to `/.well-known/oauth-protected-resource` and re-authenticate.

## Human Documentation

- Developer portal: `https://recipelogger.com/docs/developer`
- API reference: `https://recipelogger.com/docs/api`
- OpenAPI spec: `https://recipelogger.com/api/v1/openapi.json`