# Jazz MCP server: setup guide

Connect Jazz (tasks, meetings, notes and folders) to Claude and other AI apps that support the Model
Context Protocol (MCP). This is the plain-text version of https://jazzpa.com/docs/mcp, written so an AI
assistant can follow it. Last updated: 14 October 2026.

## Quick facts

- Server URL: `https://pgcfcbshyhhnhurqvqga.supabase.co/functions/v1/jazz-mcp/mcp`
- Transport: Streamable HTTP (remote server; nothing to install or run locally)
- Sign-in: OAuth 2.1 with automatic client registration. No API key is needed. The person signs in on a
  Jazz page with their Jazz email and password.
- Alternative: an MCP key from Jazz Settings, used as an OAuth client secret with client ID `jazz`
- Needs: a Jazz account with an email and password (https://jazzpa.com/sign-up)
- 21 tools: 9 that read the board, 12 that change it
- Connect once in Claude and it works everywhere that Claude account is used: Claude on the web, the
  desktop app, the mobile apps and Claude Code
- Tested with: Claude on the web and in the Claude desktop app (both sign-in methods)

## For AI assistants helping someone connect

Read these rules first:

1. **Never ask for the person's Jazz password, an MCP key, or any token in the chat.** The person types
   their password only on the Jazz approval page (jazzpa.com). An MCP key is pasted only into a secret
   field or a hidden prompt, never into a chat message or a command line.
2. **You cannot finish the sign-in yourself.** You can give exact steps and, where you can run commands,
   add the server. The person clicks Connect or authenticates, then signs in on the Jazz page.
3. **Pick the simplest method** from the table below, based on the app the person uses.
4. **Check the result** (see "Check that it works"): call `get_board_overview` and tell the person which
   Jazz email is connected, so a wrong account is caught early.
5. **Contents are private by design.** You will see titles, dates, folders and status, never descriptions
   or note text. Do not tell the person the connection is broken because of this.

## Choose how to connect

| The person uses | Simplest method | Who does what |
|---|---|---|
| Claude: web (claude.ai), desktop app or mobile app | Method 1: add a custom connector | Person: a few clicks and the Jazz sign-in |
| Claude Code, and Jazz is already connected in Claude | Nothing to set up: it appears as "claude.ai Jazz" | Check with `/mcp` or by asking for the board |
| Claude Code, not connected in Claude | Method 3: `claude mcp add`, then `claude mcp login jazz` | Assistant: runs both commands. Person: signs in on the Jazz page |
| An app that asks for an OAuth client ID and secret | Method 2: client ID `jazz`, MCP key as secret | Person: generates a key in Jazz, pastes it into the app |
| Cursor, VS Code or another MCP app | Method 4: add the server URL to its MCP settings | Person: signs in when the app opens the Jazz page |

If unsure, use Method 1. One connection in Claude covers Claude on the web, desktop and mobile, and
Claude Code signed in with the same Claude account. It needs no key and nothing to keep safe.

## Method 1: Claude app, sign in with Jazz (recommended)

Set it up on the web or in the desktop app; it then works in all Claude apps, including the mobile apps
and Claude Code, for the same Claude account. Available on all Claude plans (the Free plan allows one
custom connector).

1. In Claude, open **Customize → Connectors** (in some versions: **Settings → Connectors**).
   On **Team or Enterprise** plans an owner adds it once under **Organization settings → Connectors →
   Add → Custom → Web**; members then only click **Connect** (step 5).
2. Click **Add custom connector** (it may be behind a **+** or **Add** button).
3. Name: `Jazz`. Remote MCP server URL: `https://pgcfcbshyhhnhurqvqga.supabase.co/functions/v1/jazz-mcp/mcp`
4. Sign-in settings: leave the OAuth Client ID and Client Secret empty. If Claude asks how to sign in,
   choose **Register automatically**. Do **not** choose "Use Claude's published identity": Jazz does not
   support it yet and the connection fails.
5. Click **Add**, then **Connect**.
6. A Jazz page opens ("Allow Claude to use your Jazz account?"). **Check the Email field shows the right
   account**: it may be filled in from the account signed in to jazzpa.com in that browser, or by the
   browser's saved logins. Enter the password and click **Allow**.
7. You are sent back to Claude, connected. Start a **new chat** and ask: "What's on my Jazz board?"

Optional: on the connector's page, set each tool to "Always allow" or "Needs approval". Write tools ask
for approval by default.

## Method 2: Claude app, connect with an MCP key

For when you prefer not to use the Jazz approval page, or for apps that only accept a client ID and secret.

1. In Jazz, open **Settings → MCP** (https://jazzpa.com/settings), enter your Jazz password and click
   **Generate MCP key**. The key (starting `jzk_`) is shown once in a pop-up: copy it, tick
   "I have copied this key" and close.
2. In Claude, **Customize → Connectors → Add custom connector**. Name: `Jazz`. URL: the server URL above.
3. Open **Advanced settings** (or, if Claude asks how to sign in, choose **Use your own OAuth client**).
   OAuth Client ID: `jazz` (all lowercase). OAuth Client Secret: paste the key.
4. Click **Add**, then **Connect**. It connects straight away, with no Jazz page.

Claude cannot change a connector's sign-in settings after it is added: to switch between Method 1 and
Method 2, remove the connector and add it again.

About keys:

- **Each key connects once.** Generate a new key for every app or device. A second connection with the
  same key is refused ("This MCP key was already used to connect").
- Until it is used, treat a key like a password: anyone who has it can connect to your account.
- Keys are listed in Settings → MCP by their first characters (for example `jzk_AbC123••••`) and date.
  You can have up to 10.

## Method 3: Claude Code

**First check whether it is already there.** If Jazz is connected in Claude (Method 1 or 2) and Claude
Code is signed in with the same Claude subscription account, Jazz is already available in Claude Code as
**claude.ai Jazz** (in the terminal, VS Code, JetBrains and the Claude desktop app's Code tab; not in WSL,
and not when Claude Code uses an API key). Ask "What's on my Jazz board?" to confirm. Nothing else to do.

Otherwise, add it directly. An assistant with terminal access can run both commands; the person only
signs in on the Jazz page.

1. Add the server for all projects (`--scope user`; without it, Jazz is added only for the current folder):

   ```bash
   claude mcp add --scope user --transport http jazz https://pgcfcbshyhhnhurqvqga.supabase.co/functions/v1/jazz-mcp/mcp
   ```

2. Start the sign-in:

   ```bash
   claude mcp login jazz
   ```

   The browser opens the Jazz approval page. (Inside Claude Code you can instead type `/mcp`, choose
   **jazz** and **Authenticate**. On a machine without a browser, add `--no-browser`: it prints the link,
   and you paste the address you land on back into the terminal.)
3. On the Jazz page, which notes that the app runs on a computer, continue only if you started this
   yourself. Check the email, enter the password, click **Allow**.

To use an MCP key instead (no Jazz page): `--client-secret` takes no value; Claude Code asks for the
secret in a hidden prompt, and you paste the key there. The last `jazz` is the server's name.

```bash
claude mcp add --scope user --transport http --client-id jazz --client-secret jazz https://pgcfcbshyhhnhurqvqga.supabase.co/functions/v1/jazz-mcp/mcp
```

Then run `claude mcp login jazz`; the browser opens and returns straight away.

Check: `claude mcp get jazz` should say the server is connected. Remove: `claude mcp remove jazz -s user`.

## Method 4: other MCP apps

Any app that supports remote MCP servers over Streamable HTTP with OAuth sign-in and dynamic client
registration should work: give it the server URL and it opens the Jazz approval page by itself. These
apps have not been tested with Jazz yet. Typical configuration:

Cursor (`~/.cursor/mcp.json`):

```json
{ "mcpServers": { "jazz": { "url": "https://pgcfcbshyhhnhurqvqga.supabase.co/functions/v1/jazz-mcp/mcp" } } }
```

VS Code (`.vscode/mcp.json`):

```json
{ "servers": { "jazz": { "type": "http", "url": "https://pgcfcbshyhhnhurqvqga.supabase.co/functions/v1/jazz-mcp/mcp" } } }
```

If the app asks for an OAuth client ID and secret, use Method 2 (client ID `jazz`, MCP key as secret).
Not supported: apps that can only send a fixed API key or `Authorization` header. An MCP key is not a
bearer token.

## Check that it works

1. Ask: "What's on my Jazz board?" (this calls `get_board_overview`).
2. The answer includes the connected account's email (`user`), the timezone and open tasks. If the email
   is not the account you meant, see "Switch to another Jazz account".
3. In Claude, start a new chat after connecting: open chats keep the tool list they started with.

## What the connection can do

Read tools:

| Tool | What it does | Inputs |
|---|---|---|
| `get_board_overview` | Snapshot: open tasks, upcoming meetings, notes, folders, items shared with you, your timezone and local time. Call first | timezone |
| `list_tasks` | Your tasks, newest first. Tasks have a due date, no time | status (open, completed, all; default open), folder, limit (default 50, max 200) |
| `list_meetings` | Your meetings in time order, from the start of today | from, to (YYYY-MM-DD or YYYY-MM-DDTHH:mm), include_completed, limit (default 50, max 200), timezone |
| `list_notes` | Your notes, by title | include_archived, folder, limit (default 50, max 200) |
| `list_folders` | Your folders and folders shared with you | type (task, meeting, note), include_archived |
| `get_item` | One task, meeting or note, yours or shared: title, dates, status, folder, owner | item_type, id, timezone |
| `search` | Finds words in titles, including shared items | query, types, include_completed (default true), limit (default 25, max 100), timezone |
| `search_contents` | Finds which items mention all the given words in their description or note text; says only where, never what the text says. Whole words only | query (1 to 5 words, 3+ letters each), types (task, meeting, note, folder), limit (default 25, max 100) |
| `get_calendar` | Weekly availability, upcoming days off and meetings for the next days | days (default 7, max 60), timezone |

Write tools:

| Tool | What it does | Inputs |
|---|---|---|
| `create_task` | Adds a task | title, description, due_date (YYYY-MM-DD), repeat_interval (daily, weekly, monthly, yearly), folder |
| `schedule_meeting` | Adds a meeting; reminders 15 minutes before and at the start | title, scheduled_at, description, repeat_interval, folder, timezone |
| `create_note` | Saves a note | title, content, folder |
| `update_task` | Changes a task; only the fields given change; null clears description, due_date or repeat | id, title, description, due_date, repeat_interval |
| `update_meeting` | Changes or reschedules a meeting; a new time re-arms its reminders | id, title, description, scheduled_at, repeat_interval, timezone |
| `update_note` | Changes a note's title or text, or archives it. New text replaces the whole note | id, title, content, archived |
| `set_task_completed` | Marks a task done or reopens it | id, completed |
| `set_meeting_completed` | Marks a meeting done or reopens it | id, completed |
| `delete_task` | Permanently deletes one of your own tasks. Confirm with the person first | id |
| `create_folder` | Creates a folder for tasks, meetings or notes; reuses one with the same name | name, folder_type |
| `move_to_folder` | Puts one of your own items into a folder of the same type, or takes it out (folder: null) | item_type, item_id, folder |
| `share_item` | Adds another Jazz user, by email, to one of your own items; they are emailed and notified. Confirm the recipient first | item_type, item_id, email |

Ids come from the list, search and overview tools; never guess them. Items shared with you can be read,
edited and completed (the owner and collaborators are notified), but not deleted, moved or re-shared.

Not available through the connector: deleting meetings or notes (notes can be archived); renaming,
archiving or deleting folders; removing someone from a shared item; reading descriptions, note text,
folder descriptions, comments or past Jazz chats; attachments and comments; changing availability, days
off, profile or account settings; talking to the Jazz assistant itself.

Things to ask: "What's on my Jazz board today?" · "Add a task to renew my passport, due next Friday." ·
"Schedule a call with Priya tomorrow at 3pm about the Q4 budget. Check I'm free first." · "Which task has
the Acme invoice details?" · "Move my grocery tasks into a folder called Errands." · "Mark the dentist
task as done and move the team sync to Thursday at 10."

## Dates, times and timezones

- Meeting times are read and written in the person's Jazz timezone (Settings → Personal Info). On
  Auto-detect, the timezone of the browser used to connect is used, saved when they click Allow or
  generate a key.
- Results include `timezone` and `timezone_source`: `requested`, `settings`, `app` or `unknown`. With
  `unknown`, times are in UTC: ask the person for their timezone and pass it as `timezone` (IANA name,
  for example `Asia/Kolkata`). Scheduling from a local time without an offset is refused until then.
- Pass meeting times as local wall-clock `YYYY-MM-DDTHH:mm` (for example `2026-10-20T15:00`) or as ISO
  8601 with an offset (`2026-10-20T09:30:00Z`).
- Tasks have a due date but no time. Set `repeat_interval` only when the person asks for a repeating item.

## Privacy and security

- **Acts as the person.** Every request runs as their Jazz account; the database returns only rows they
  may see.
- **Sent to the AI app:** the person's email address; titles, ids, due dates, meeting times, status, who
  completed an item, repeat settings, folders and creation dates; for shared items, who shared them (name
  or email); weekly availability, days off and timezone.
- **Never sent:** descriptions, note text, folder descriptions, comments, past Jazz chats, attachments,
  passwords. The server does not even read them, except `search_contents`, which reports only which
  items match. The AI app can still write a description or note text the person gives it.
- **Note edits replace the whole note**, because the AI app cannot see the old text. To add to a note,
  open it in Jazz.
- **Passwords stay with Jazz.** Each connection gets its own sign-in session, separate from the browser.
- **Tokens:** access tokens last about an hour, renew automatically, and work only with this server; they
  cannot be used to read Jazz data any other way.
- **What Jazz stores for this feature:** the list of MCP keys (an id, the first characters and the date,
  never the key itself) and the timezone used when connecting. The hosting provider (Supabase) keeps
  request logs (time, path, status, IP address, app name) for a short period.
- What the AI app receives is handled under that app's terms and privacy policy. Jazz Privacy Policy:
  https://jazzpa.com/privacy

## Disconnect, revoke, switch accounts

- **Claude:** Customize → Connectors → Jazz → Disconnect (or remove the connector).
- **Claude Code:** `claude mcp remove jazz -s user` (use the scope it was added with).
- **One MCP key:** Jazz Settings → MCP → Revoke next to the key (click twice). Its connection stops at the
  next token renewal, within an hour.
- **All MCP keys:** Settings → MCP → Revoke all MCP keys. Connections made without a key (Methods 1 and 3)
  are not affected and are not listed in Jazz: remove them in the app.
- **Switch to another Jazz account:** disconnect, connect again, and on the Jazz page replace the email
  before clicking Allow. Browsers may refill a saved login: check the field just before you click.

## Troubleshooting

| Message or symptom | What to do |
|---|---|
| Connected as the wrong Jazz account | Disconnect, connect again and fix the email on the Jazz page before clicking Allow |
| Unknown client_id | With an MCP key the client ID must be `jazz`, all lowercase. Without a key, leave client ID and secret empty |
| This MCP key was already used to connect | Each key connects once. Generate a new key in Jazz Settings → MCP |
| This MCP key no longer works: its Jazz sign-in has ended | The sign-in inside the key ended, for example after a password change. Generate a new key |
| This MCP key has been revoked | The key was removed from the list in Jazz Settings. Generate a new one |
| You already have 10 MCP keys | Revoke a key you no longer use, then generate a new one |
| This connection request is invalid or has expired | The Jazz page is valid for 15 minutes. Start again with Connect |
| Your sign-in could not be verified | Enter the Jazz email and password again on the Jazz page |
| A connector with this URL already exists (Claude) | Claude allows one connector per URL: open the existing Jazz connector, or remove it and add it again |
| Adding the connector fails, or Claude only offers other sign-in options | Check the URL character by character; it must end in `/jazz-mcp/mcp` |
| Connecting fails after choosing "Use Claude's published identity" | Jazz does not support that yet. Remove the connector and add it again with "Register automatically" |
| New or changed tools do not appear (Claude) | On the connector's page use "Refresh tools list", then start a new chat |
| Claude Code shows "Needs authentication" | Run `claude mcp login jazz` in a terminal, or `/mcp` → jazz → Authenticate inside Claude Code |
| Claude Code only has Jazz in one folder | It was added without `--scope user`. Remove it and add it again with `--scope user` |
| "I can't see the description / note text" | Expected: contents are private. Use `search_contents` to find the item; read it in Jazz |
| Meeting times are a few hours off | Set the timezone in Jazz Settings → Personal Info, or tell the assistant the timezone |

Still stuck: rakesh@infugin.com

## Technical reference

Base URL: `https://pgcfcbshyhhnhurqvqga.supabase.co/functions/v1/jazz-mcp`

| Method | Path | Purpose |
|---|---|---|
| POST | `/mcp` | MCP endpoint (Streamable HTTP, stateless, JSON responses; GET returns 405) |
| GET | `/.well-known/oauth-protected-resource/mcp` | Protected resource metadata (RFC 9728) |
| GET | `/.well-known/oauth-authorization-server` | Authorization server metadata (RFC 8414) |
| GET | `/.well-known/openid-configuration` | The same metadata, for clients that look here |
| POST | `/register` | Dynamic client registration (RFC 7591) |
| GET | `/authorize` | Authorization endpoint; redirects to the Jazz approval page |
| POST | `/token` | Token endpoint (`authorization_code`, `refresh_token`) |
| GET | `/health` | Status |
| POST | `/oauth/request`, `/oauth/approve`, `/oauth/credentials` | Used by the Jazz web app only |

- **Protocol:** MCP versions up to `2025-11-25`. A client that first tries `2026-07-28` gets
  `400 Unsupported protocol version` and falls back to `initialize`; one such 400 per connection is
  expected. No sessions and no server-sent event stream.
- **Discovery:** a request without a token gets `401` with
  `WWW-Authenticate: Bearer resource_metadata="…/.well-known/oauth-protected-resource/mcp"`. The metadata
  names this server as its own authorization server.
- **Authorization:** OAuth 2.1 authorization code flow with PKCE (`S256` required). The authorization
  response includes `iss` (RFC 9207). The `resource` parameter (RFC 8707), if sent, must be the MCP URL;
  anything else is refused with `invalid_target`. Scope: `jazz`.
- **Clients:** dynamic registration with `token_endpoint_auth_method` `none`, `client_secret_post` or
  `client_secret_basic`; up to 10 redirect URIs, `https` or `http` loopback (any port). Registrations are
  signed, not stored. Client ID Metadata Documents (CIMD) are not supported.
- **Pre-authorized client:** client ID `jazz` with an MCP key as client secret (`client_secret_post` or
  `client_secret_basic`). Allowed redirects: `https://claude.ai/api/mcp/auth_callback`,
  `https://claude.com/api/mcp/auth_callback`, `http://localhost/callback` and `http://127.0.0.1/callback`
  (loopback on any port). A key works only while listed in the person's Jazz Settings; revoking takes
  effect at the next token refresh.
- **Tokens:** the token endpoint takes `application/x-www-form-urlencoded`. Access tokens (`jma_…`) are
  opaque, last about an hour (`expires_in`) and are accepted only by this server. Refresh tokens rotate on
  every use; keep the newest. Authorization codes last 2 minutes; Jazz approval requests 15 minutes.
- **CORS:** any origin (bearer tokens only, no cookies).
- **Tools:** annotated with `readOnlyHint`, `destructiveHint`, `idempotentHint` and `openWorldHint`. The
  server sends usage instructions to the model on `initialize`. Tool failures return `isError: true` with a
  readable message; OAuth errors are JSON `{ "error", "error_description" }`.

## Changelog

- **14 October 2026:** descriptions, note text, folder descriptions, comments and past chats are no longer
  sent to AI apps; `search_contents` added (finds where words appear without revealing text) and
  `search_conversations` removed; access tokens work only with this server; MCP keys are listed in
  Settings and can be revoked one by one; clearer messages for used or ended keys; reopening an item
  clears who completed it.
- **13 October 2026:** first release: sign in with Jazz (OAuth) or an MCP key, read and write tools.