# Zernote auth.md

This document describes how AI agents and MCP clients authenticate with the Zernote remote MCP server.

## Audience

AI agents, autonomous clients, and MCP-compatible tools connecting to Zernote's hosted MCP endpoint at `https://zernote.com/mcp`.

## Authentication

Zernote uses **OAuth 2.1 with PKCE** (Proof Key for Code Exchange). Clients should perform **dynamic client registration** before starting the authorization flow:

- Registration endpoint: [https://zernote.com/oauth/register](https://zernote.com/oauth/register)

Human-facing setup for Claude: [https://zernote.com/connect-claude](https://zernote.com/connect-claude).

## Protected resource

- MCP endpoint: `https://zernote.com/mcp`
- Transport: Streamable HTTP

## Metadata

Discover authorization and resource metadata from these well-known URLs:

- **Authorization server metadata:** [https://zernote.com/.well-known/oauth-authorization-server](https://zernote.com/.well-known/oauth-authorization-server)
- **Protected resource metadata (PRM):** [https://zernote.com/.well-known/oauth-protected-resource](https://zernote.com/.well-known/oauth-protected-resource)
- **PRM (MCP path):** [https://zernote.com/.well-known/oauth-protected-resource/mcp](https://zernote.com/.well-known/oauth-protected-resource/mcp)
- **MCP Server Card:** [https://zernote.com/.well-known/mcp/server-card.json](https://zernote.com/.well-known/mcp/server-card.json)

## Scopes

Request only the scopes your agent needs. If the client omits `scope`, all eight scopes below are granted by default.

| Scope | Access |
|-------|--------|
| `folders:read` | List and read research folders |
| `folders:write` | Create and rename folders |
| `interviews:read` | Read interviews, summaries, JTBD trees, and claim-cards |
| `interviews:write` | Rename, move, retranscribe, assign speakers, and toggle voiceprint |
| `interviews:upload` | Upload interviews via the in-chat widget (audio/video/text/PDF) |
| `transcripts:read` | Read interview transcript windows |
| `search:read` | Semantic search across interviews and notes |
| `notes:write` | Write or replace interview notes and summaries |

## Using credentials

After obtaining an access token, send it on every MCP request:

```
Authorization: Bearer <access_token>
```

The token must be valid for the `https://zernote.com/mcp` resource and include the scopes required by the tools you call.

## Typical MCP capabilities (after OAuth)

- Read folders / interviews with summary-first and JTBD-first workflows
- Search and cite quote deep-links (`/research/interview/{id}?t={seconds}`)
- Read coded claim-cards (`cards_read`) and JTBD trees (`jtbd_read`)
- Upload into Inbox via `upload_interview` (Claude MCP App widget)
- Confirm interviewer speakers when voiceprint flags `need_approve_speakers`
- Retranscribe with a chosen language when transcript quality looks corrupted
- Write or replace notes/summaries only when the human asks

## Device authorization (Zernotik)

Zernotik (desktop/companion) uses a separate RFC 8628 device-code flow against `/oauth/device/code` with a fixed public client and API scope. That path is **not** the primary MCP agent registration flow. MCP clients should use DCR + authorization code + PKCE as above.

## Human setup

For step-by-step setup in Claude Desktop, Claude.ai, Claude Code, or other human-facing clients, see [https://zernote.com/connect-claude](https://zernote.com/connect-claude).