Setup guide

Connect your AI to zimmboard

Tested & supported

✓ Claude ✓ ChatGPT ✓ Le Chat ✓ Cursor ✓ VS Code Claude Code · testing Gemini · untested Perplexity · untested Grok · untested

Checked agents are verified by us end-to-end — sign-in, reading a board, live updates, and the session wrap. The rest speak the same protocol and should work; we just haven't personally confirmed them yet, so we won't claim it.

Add my AI Using something that isn't listed? Tell us and we'll test it.

zimmboard is a shared planning board your AI can read and update. Each AI connects a little differently — pick yours below. The in-app Connect AI drawer (on any board) generates the keys and ready-to-paste setup for whichever path you choose, and we'll add walkthroughs for more AIs here as each one is tested and verified.

1. Which AI are you using?

Chat apps

Coding tools

✓ tested end to end by us. The others use the same standard sign-in and should work — if you try one, tell us how it went and we’ll mark it verified.

Claude — one-click connector (recommended)

The zimmboard connector is a remote MCP server with OAuth sign-in. One URL, sign in once, no keys to manage, works on every device. Fully verified end-to-end.

In Claude, open Settings → Connectors → Add custom connector (on claude.ai or in the Claude desktop/mobile apps).
Enter the connector URL: https://mcp.zimmboard.com/mcp
Claude opens a ZimmBoard sign-in page. Log in with your zimmboard email and password and click Allow access.
Done. Claude can now see the boards your account can see — and nothing else. Access is scoped per user; teammates connect their own AI with their own login.

Try it: start a new chat and say “Load my zimmboard board and ground yourself, then help me work.” Claude will list your boards, read the one you pick, and pick up exactly where the last session left off.

ChatGPT — MCP connector verified

Requires a paid ChatGPT plan (Plus or higher — Free has no custom-app support). Verified end-to-end on ChatGPT Plus: OAuth sign-in, board reads, live task updates, the one-shot plan import, and the session wrap.

In ChatGPT: profile → Settings → Plugins → enable Developer mode. (OpenAI renames this area often — it has also lived under Connectors / Apps; look for the developer toggle.)
Add a custom plugin with the server URL https://mcp.zimmboard.com/mcp and authentication OAuth.
ChatGPT opens the ZimmBoard sign-in page. Log in and click Allow access.
In a chat, enable ZimmBoard from the + / tools menu, then say “Load my zimmboard board and ground yourself.”

Alternative: a custom GPT with an Action

Prefer a dedicated GPT? In your board, open Connect AI → ChatGPT — it gives you the Action schema URL, a key, and ready-made GPT instructions (GPTs → + Create → Configure → Actions → Import from URL → Authentication: API Key, Bearer). Also requires a paid plan; Free gets neither path.

Le Chat (Mistral) — MCP connector verified

Works on Le Chat's free plan. Verified end-to-end: OAuth sign-in, board reads, live task updates, the one-shot plan import (nested sub-projects included), decision logging, and the session wrap.

At chat.mistral.ai, open the side panel (toggle at top-left), expand the Intelligence group, and click Connectors.
Click + Add Connector, switch to the Custom MCP Connector tab, name it ZimmBoard, and enter the server URL https://mcp.zimmboard.com/mcp.
Le Chat opens the ZimmBoard sign-in page — log in with your zimmboard account and click Allow access.
In a chat, open the Tools menu and tick ZimmBoard, then say “Load my zimmboard board and ground yourself.”

Cursor — MCP connector verified

Works on Cursor's free plan. Verified end-to-end, including the trickier paths: one-shot plan import with nested sub-projects, board files with surgical find-and-replace edits, and sync mode reconciliation.

Create Cursor's global MCP config. In Terminal:

mkdir -p ~/.cursor && cat > ~/.cursor/mcp.json <<'EOF'
{ "mcpServers": { "zimmboard": { "url": "https://mcp.zimmboard.com/mcp" } } }
EOF

(Or per-project: the same JSON at .cursor/mcp.json in your project root.)

Fully quit Cursor (Cmd-Q) and reopen it.
Open Cursor Settings → Tools & MCP. Click zimmboard to start sign-in — your browser opens the ZimmBoard page; log in and click Allow access. You should see a green dot and 21 tools.
Open the chat with Cmd-L and switch the mode dropdown to Agent, then say “Load my zimmboard board and ground yourself.”

If nothing happens: Cursor's Ask mode can't call tools — it will describe what it would do instead of doing it. Switch to Agent mode. For connection errors, Cmd-Shift-U → choose MCP from the dropdown shows the real reason.

VS Code (GitHub Copilot) — MCP connector verified

Works with Copilot's free tier. Verified end-to-end: OAuth sign-in, board reads, the one-shot plan import with nested sub-projects, task updates, decision logging, and the session wrap.

Install the GitHub Copilot extension and sign in (the free tier includes agent mode).
Cmd-Shift-P → MCP: Add Server → HTTP → URL https://mcp.zimmboard.com/mcp → name it zimmboard → scope Global.
Open Copilot Chat and switch the mode dropdown to Agent.
Say “List my zimmboard boards” — the first tool use opens the ZimmBoard sign-in page. Log in, click Allow access, and you're connected.

Nothing happening? Ask mode can't call tools — it will describe what it would do instead of doing it. Switch to Agent mode.

Perplexity — MCP connector not yet tested

Requires Perplexity Pro, Max, or Enterprise — free accounts can’t add connectors. Perplexity documents the same standard sign-in our connector uses, so it should work; we haven’t run it end to end ourselves yet.

In Perplexity, open Account settings → Connectors, click + Custom connector, and choose Remote.
Name it ZimmBoard and enter the server URL https://mcp.zimmboard.com/mcp. For authentication choose OAuth 2.0 and leave the client ID and secret empty — ZimmBoard registers Perplexity automatically.
Click the new connector to sign in with your zimmboard account, then click Allow access.
Enable ZimmBoard for your thread and ask “Load my zimmboard board and ground yourself.”

Tried it? Tell us how it went — one working report and we’ll mark Perplexity verified.

Grok — MCP connector not yet tested

Requires a paid Grok plan. xAI documents custom MCP connectors on grok.com; we haven’t run it end to end ourselves yet.

Go to grok.com/connectors, click New Connector, and choose Custom.
Enter the server URL https://mcp.zimmboard.com/mcp.
Grok should open the ZimmBoard sign-in page — log in and click Allow access.
In a chat, ask “Load my zimmboard board and ground yourself.”

If no sign-in page appears and Grok can’t see any ZimmBoard tools, remove the connector and add it again — and please tell us, so we can fix it for everyone.

Tried it? Tell us how it went — one working report and we’ll mark Grok verified.

Claude Code — plugin not yet tested

The ZimmBoard plugin bundles the connector and the session-ritual skill. Installing it from GitHub is verified; the sign-in step hasn’t had a full live run yet.

In Claude Code, run /plugin marketplace add azimm1984/zimmboard-plugin
Then run /plugin install zimmboard@zimmboard
Run /mcp, choose zimmboard, and sign in with your zimmboard account.
Ask “Load my zimmboard board and ground yourself.”

Just want the connector, without the skill? Run claude mcp add --transport http zimmboard https://mcp.zimmboard.com/mcp, then /mcp to sign in.

Tried it? Tell us how it went — one working report and we’ll mark Claude Code verified.

Codex (OpenAI) — MCP connector not yet tested

Works in the Codex CLI and the Codex IDE extension, which share one config. You’ll need Codex installed and signed in.

In Terminal, add the server:

codex mcp add zimmboard --url https://mcp.zimmboard.com/mcp

Sign in:
```
codex mcp login zimmboard
```
Your browser opens the ZimmBoard page — log in and click Allow access.
Start codex, run /mcp to confirm zimmboard is connected, then ask “Load my zimmboard board and ground yourself.”

Tried it? Tell us how it went — one working report and we’ll mark Codex verified.

Gemini CLI — MCP connector not yet tested

Free with a Google account. (The Gemini chat app doesn’t accept custom connectors for individual accounts yet — we’ll add it when it does.)

In Terminal, add the server:

gemini mcp add -s user --transport http zimmboard https://mcp.zimmboard.com/mcp

Start gemini and run /mcp auth zimmboard — your browser opens the ZimmBoard sign-in; log in and click Allow access.
Run /mcp to confirm it’s connected, then ask “Load my zimmboard board and ground yourself.”

Tried it? Tell us how it went — one working report and we’ll mark Gemini CLI verified.

Windsurf — MCP connector not yet tested

In Windsurf, open the Cascade panel, click the MCP (hammer) icon, then Configure to open ~/.codeium/windsurf/mcp_config.json.

Add ZimmBoard (merge it with any servers already listed):

{ "mcpServers": { "zimmboard": { "serverUrl": "https://mcp.zimmboard.com/mcp" } } }

Save, then click Refresh in Cascade. Complete the ZimmBoard sign-in when your browser opens.
Ask Cascade “Load my zimmboard board and ground yourself.”

Tried it? Tell us how it went — one working report and we’ll mark Windsurf verified.

Zed — MCP connector not yet tested

Open Settings → AI → MCP Servers, click Add Server → Add Remote Server, and enter https://mcp.zimmboard.com/mcp. Or add it to your settings.json:
```
{ "context_servers": { "zimmboard": { "url": "https://mcp.zimmboard.com/mcp" } } }
```
Zed prompts you to sign in — log in with your zimmboard account and click Allow access.
In the Agent panel, ask “Load my zimmboard board and ground yourself.”

Tried it? Tell us how it went — one working report and we’ll mark Zed verified.

Any AI — paste-in prompt or raw API

The real universal path is the MCP connector: https://mcp.zimmboard.com/mcp works in any MCP-capable client — Claude, ChatGPT (paid plans), Le Chat, Perplexity, Cursor, VS Code, Windsurf, Zed, and more. The paste-in path below is for agents that can send authenticated HTTP requests — CLI agents, scripts, and API stacks. Consumer chat apps (like ChatGPT or Gemini) can't send auth headers from a chat; use their MCP path instead.

Any LLM that can make authenticated HTTP calls can use the board API with a Bearer key. In a board, open Connect AI → Any AI and it generates a single paste-in message with a fresh key built in — nothing to wire up. (Keys can be created read-only if the agent should never write.)

Under the hood it's two calls:

« start of session »
GET https://zimmboard.com/api/v1/boards/{id}/context
Authorization: Bearer YOUR_KEY

« end of session »
POST https://zimmboard.com/api/v1/boards/{id}/wrap
{"summary": "what I did", "session_tag": "Chat 12",
 "task_updates": [{"id": 3, "done": true}],
 "new_tasks": [{"project_id": 1, "text": "follow up"}],
 "carry_forward": ["next-session item"]}

The context response documents the full mid-session write API (add/check/edit tasks, log decisions, edit files, import plans), so your agent learns the rest by reading the board. So far this path is verified working with Claude; it should work with any agent that can send authenticated requests, and we'll note more agents here as they're tested.

2. The session ritual

The whole product is one loop:

Session start — your AI reads the board (board_context): open tasks with ids, deadlines, attached files, the last session's note and carry-forward items, decisions, and who changed what since the last wrap.
During the session — it works the board live: checks tasks off the moment they're finished, adds newly-discovered work, and logs decisions as they're made. You watch the board update in real time.
Session end — it wraps (wrap_session): a short summary note, a carry-forward list for next time, and any final check-offs, all in one call. The next session — even in a different chat, or a different AI — starts from there.

You don't have to ask for this. The connector hands your AI the ritual when it connects, and the ZimmBoard skill teaches Claude the finer points.

3. What the connector can do

The Claude connector exposes 21 tools. Every tool is annotated for safety: read-only tools are marked read-only, and destructive ones (deletes, file overwrites) are marked destructive so your AI client can ask before using them.

Area	Tools
Read	List boards · Read board context · List board files · Read board file
Session ritual	Wrap session · Log a decision
Projects & tasks	Add / Update / Delete project · Add / Update / Delete task
Board files	Create · Replace content · Edit (find & replace) · Delete
Whole plans	Create board · Import or sync a plan (build a board from a plan file in one call; re-run to reconcile) · the same import as a JSON string, for clients that can't pass nested lists
See it	Show board (renders your board inside the chat — progress, projects, and checkboxes you can click)
Code repos	Export AGENTS.md (a section your coding agents read at startup)

See your board inside the chat

Ask “show me my board.” In Claude, ChatGPT, and VS Code the board renders right in the conversation: progress bar, projects, and checkboxes. Check a task off there and it saves to zimmboard immediately, and your AI is told what you did. Clients without interactive views get a text summary instead.

Teach Claude the ritual: the ZimmBoard skill

The skill goes deeper than the connector’s built-in instructions: what to read first, how to log decisions, how to wrap so the next session loses nothing.

Claude (web & desktop): download zimmboard-skill.zip. In Claude, open Customize → Skills, click +, choose Upload a skill, and pick the zip. Skills need Code execution and file creation turned on in Settings → Capabilities.
Claude Code: install the ZimmBoard plugin, which bundles the connector and the skill. Run /plugin marketplace add azimm1984/zimmboard-plugin, then /plugin install zimmboard@zimmboard, then /mcp → zimmboard to sign in. Source: github.com/azimm1984/zimmboard-plugin.

Reach coding agents with AGENTS.md

Coding agents like Codex, Cursor, Copilot, and Gemini CLI read a repo’s AGENTS.md when they start. Download it from your board’s Files tab (↓ AGENTS.md), or ask your AI to “export the AGENTS.md for this board” and save it in the repo. It tells those agents how to reach the live board and carries a snapshot of the plan.

4. Security & revoking access

Scoped per account: a connected AI sees only the boards your zimmboard account can see. The connector's OAuth token is bound to your user; keys are stored only as hashes.
Read-only mode: keys can be created read-only; write tools then return a clear refusal.
Audit trail: every agent action — task check-offs, adds, file edits — is attributed in the board's Activity tab, down to which person and which AI (for example, “Aaron · ChatGPT”), and in the "Activity since the last wrap" section of context.
Revoke anytime: delete a key in Connect AI, or disconnect the connector in Claude's settings. Revoking a key cuts off any agent using it immediately.

5. Troubleshooting

"Reconnect the ZimmBoard connector" in a tool reply — your authorization lapsed. Disconnect and reconnect the connector in Claude's settings and sign in again.
Your AI can't see a board — confirm your zimmboard account owns it or has been invited to it. The connector never shows boards outside your account.
File shows "stored" instead of "readable" — that format has no extractable text (e.g. an image). Markdown, code, CSV, Excel, and most PDFs are readable to agents.

6. Support

Stuck, or found a bug? Email support@zimmboard.com. See also our privacy policy for how your data is handled.