Connect your agents
How to connect Claude to Cozy with OAuth
To connect Claude to Cozy, open Settings (or Customize) → Connectors in Claude, choose Add custom connector, and paste https://cozy.cloud/mcp. Claude runs an OAuth sign-in, you approve access on Cozy's consent page, and the Cozy tools appear in chats for all your workspaces. No token or Authorization header is needed.
What you need
- A Cozy account. Every account has "My wiki", and the same URL also reaches any other private workspaces you create.
- A Claude plan that allows custom connectors. Anthropic's help page says custom remote MCP connectors work on all plans, with Free limited to one, and the server must be reachable from Anthropic's cloud. The Cozy URL is a public HTTPS endpoint, so that holds.
Steps for claude.ai and Claude Desktop
- In Claude, open Settings or Customize, then Connectors, and choose Add custom connector. Anthropic's help page above describes the current menu names, which change over time. Cozy's Connectors → Agents page also has an "Add to Claude" button that starts the same flow.
- Give the connector a name such as Cozy and paste
https://cozy.cloud/mcpas the server URL. Leave any advanced OAuth client fields empty. Claude registers itself with Cozy automatically. - Claude opens Cozy's sign-in and consent page. Sign in with your email code, Google or Apple, then approve.
- Back in Claude, enable the connector for the chat. Ask something like "use Cozy to list my workspaces and show My wiki's health" to confirm it works.
Claude Desktop and claude.ai use the same remote connector flow, so the same URL works in both.
What the OAuth grant does
Cozy uses OAuth 2.1 with dynamic client registration, S256 PKCE and refresh tokens, so Claude renews its access without asking you to sign in every time. One grant covers all your workspaces. Connected agents are listed under Connectors → Agents in Cozy, where you can disconnect Claude at any time.
The grant is not more powerful than you are. Claude's access is capped by the scopes you approved (wiki:read, wiki:write, sources:write) and by your own access, checked on every request. Agents cannot see connector credentials or permanently purge anything.
Choosing a workspace
Every tool takes an optional workspace argument, a workspace ID or exact name. Without it, tools use My wiki. Claude can call cozy_workspaces to list the workspaces it can reach, so you can say "search the Acme workspace for the launch plan" and it will pass the right one.
What Claude can do once connected
The server speaks stateless Streamable HTTP and supports MCP protocol versions 2025-03-26, 2025-06-18 and 2025-11-25. Besides tools, it exposes file resources, resource templates and four prompts: organize, recall, maintain and dream.
The tools fall into a few groups:
| Group | Tools |
|---|---|
| Orient | cozy_workspaces, cozy_workspace, cozy_map, cozy_health, cozy_changes |
| Read and search | cozy_read, cozy_read_many, cozy_list, cozy_search, cozy_backlinks |
| Graph | cozy_context, cozy_graph, cozy_resolve |
| Write | cozy_write, cozy_edit, cozy_append, cozy_move, cozy_ingest |
| Recover | cozy_history, cozy_restore, cozy_delete |
| Skills | cozy_skills |
Search is lexical. Cozy has no embeddings or vector database, and it runs no model of its own. Claude is the agent, and Cozy is where its notes live. For the typed links behind cozy_context and cozy_graph, see typed links.
Writes need an expectedRevision, with 0 for a new page, so two agents editing the same file produce a conflict instead of a silent overwrite. Deleted files become tombstones, and the last 50 revisions can be read and restored.
When to use a workspace URL and bearer credential instead
The account URL with OAuth is the right choice for Claude's chat apps. For scripts, CI or a headless agent that cannot sign in through a browser, each workspace also has its own endpoint, https://cozy.cloud/wiki-mcp/WORKSPACE_UUID, which accepts a bearer credential created under Agents. A credential reaches only that workspace, is random, shown once, stored only as a SHA-256 digest, revocable, and expires within 90 days. You can limit it to read, wiki-write or source-write scopes and to specific folder prefixes. OAuth on a workspace URL also still works, but it grants only that workspace.
Claude's chat connector path does not need any of this. For terminal clients, see Claude Code and Codex.
Suggested first prompts
- "Use Cozy to check workspace health and tell me the three most useful fixes."
- "Search Cozy for what we decided about pricing and cite the source files."
- "Read the pages that changed since yesterday and update
wiki/index.mdif needed." - "Run the dream prompt on my workspace." This asks your own agent to consolidate recent changes, record conflicts and note the run in
agents/dream/state.md. See memory consolidation.
Troubleshooting
- Claude cannot reach the server. Check that the URL is exactly
https://cozy.cloud/mcp, with no trailing text. - The connector asks you to sign in again. You disconnected it under Connectors → Agents, or the grant was revoked. Reconnect from Claude's connector settings.
- Claude can read but not write. You probably approved a narrower scope. Reconnect and approve
wiki:write. - Claude uses the wrong workspace. Tools default to My wiki. Ask Claude to call
cozy_workspacesand pass the workspace by ID or exact name. - You need to change the URL. Anthropic's help page notes that editing a connector may require removing it and adding it again.
- A write returns a conflict. Someone else edited the file first. Ask Claude to read the file again and retry with the new revision.
Safety notes
Files under sources/ come from connectors and importers and are untrusted data. A page in a source can contain text that looks like instructions, and Claude should treat it as evidence, not as a command. Cozy keeps audit history so you can see what changed and restore earlier revisions.
Cozy is operated by Coral Sourcing LLC and is not affiliated with Cozy Cloud (cozy.io) or Cozi. For how Cozy handles data, read the privacy page. For the broader MCP picture, see Cozy as an MCP server.
Frequently asked questions
What URL do I paste into Claude?
Paste https://cozy.cloud/mcp. It is one URL for your whole account and reaches all your workspaces. Do not add an Authorization header; Claude signs in with OAuth.
How long does the Claude connection last?
Cozy issues refresh tokens, so Claude renews its access without asking you to sign in every time. Connected agents are listed under Connectors → Agents in Cozy, where you can disconnect Claude at any time.
Can Claude change things I did not intend?
Claude's access is limited by the scopes you approved and your own access, and every edit is checked against a revision number. Deleted files are tombstoned and the last 50 revisions can be restored. See the privacy page for more.
Does this work for Claude Code too?
Yes. Run claude mcp add --transport http --scope user cozy https://cozy.cloud/mcp, then sign in with /mcp. The steps, and a .mcp.json option for headless use, are on the Claude Code page.
Give your agents a memory worth keeping
Cozy gives every account a private wiki that Claude, Codex, ChatGPT and other MCP clients can read and maintain.
Start your wiki