How to connect Claude Code to your Cozy wiki

Updated · By the Cozy team

To connect Claude Code to Cozy, run claude mcp add --transport http --scope user cozy https://cozy.cloud/mcp, then run /mcp in Claude Code and sign in. You approve access on Cozy's consent page, and one URL reaches all your workspaces. For CI and headless agents, use a project .mcp.json that points at a workspace URL with a bearer token instead.

Cozy is a private wiki and cloud file space for each person and their AI agents. Your account has one hosted MCP endpoint, so Claude Code can read and write the same pages you see in the web app and the Mac app, in any of your workspaces. Cozy runs no model itself. Claude Code is the agent, and Cozy is the memory it reaches over MCP.

This page covers the OAuth setup, the .mcp.json option for headless use, what to check after connecting, and what the connection can and cannot do.

What you need

The endpoint is stateless Streamable HTTP. It supports MCP protocol versions 2025-03-26, 2025-06-18 and 2025-11-25.

Option 1: OAuth with the account URL

This is the setup to use on your own machine.

  1. Add the server once for your user, so it is available in every project:
claude mcp add --transport http --scope user cozy https://cozy.cloud/mcp
  1. Start Claude Code and run /mcp. Choose cozy and sign in. Your browser opens Cozy's consent page; review the scopes and approve.

Cozy uses OAuth 2.1 with dynamic client registration, S256 PKCE and refresh tokens, so Claude Code registers itself and 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 Code at any time.

Every tool takes an optional workspace argument, a workspace ID or exact name. Without it, tools use My wiki. cozy_workspaces lists the workspaces Claude Code can reach.

Option 2: .mcp.json with a bearer token

This is the setup to use for scripts, CI and headless agents that cannot sign in through a browser. It uses a per-workspace endpoint, https://cozy.cloud/wiki-mcp/WORKSPACE_UUID, shown under Agents in Cozy, and a credential that reaches only that workspace.

  1. Open Agents in Cozy and create a bearer credential. Choose the scopes it needs (see the table below). Copy it right away, because Cozy shows it once.
  2. Export it in your shell profile or secret manager as COZY_MCP_TOKEN.
  3. Add a .mcp.json file at the root of your project, or merge this into an existing one.
{
  "mcpServers": {
    "cozy": {
      "type": "http",
      "url": "https://cozy.cloud/wiki-mcp/WORKSPACE_UUID",
      "headers": {
        "Authorization": "Bearer ${COZY_MCP_TOKEN}"
      }
    }
  }
}

Replace WORKSPACE_UUID with the UUID from your workspace URL. The ${COZY_MCP_TOKEN} reference reads the environment variable when Claude Code starts, so the token never lands in the file. That matters when .mcp.json is committed to a repository. Commit the file, keep the token out of it, and each machine or CI job uses its own credential.

Start Claude Code from a shell where the variable is set. If you launch it from a desktop app that did not inherit your shell environment, the header will be empty and the server will reject the request.

A workspace URL with no header also accepts OAuth, but that grant reaches only that workspace. For interactive use, the account URL in Option 1 is simpler.

OAuth or bearer: which to pick

OAuth (account URL)Bearer credential (workspace URL)
Setupclaude mcp add, then sign in with /mcpCreate in Agents, export an env var
ReachesAll your workspacesOne workspace
LifetimeRenews with refresh tokensExpires within 90 days
Scopeswiki:read, wiki:write, sources:write, capped by your own accessread, wiki-write, source-write, capped by your own access
Folder limitsNot offeredOptional folder-prefix grants
Good forInteractive use on your own machineCI, scripts, shared project config

Bearer credentials are random, shown once and stored as SHA-256 digests. You can revoke them at any time.

Scopes and what Claude Code can touch

Every request is checked against the agent's scopes, and an agent never gets more access than you, the person who connected it, have yourself.

OAuth scopeBearer scopeWhat it allows
wiki:readreadSearch, read, list and traverse the graph
wiki:writewiki-writeWrite curated pages in wiki/, skills/ and agents/
sources:writesource-writeAdd evidence to sources/, for example through ingest

Grant only the scopes the job needs. For a research agent that should never edit pages, read alone is enough. Bearer credentials can also be restricted to folder prefixes. Agents cannot see connector credentials or permanently purge anything.

Check the connection

Start Claude Code and run /mcp. The cozy server should appear as connected. Then ask the agent to call cozy_workspaces and describe what it finds. A good first real task is cozy_map, which returns the index grouped by type, followed by cozy_search for a topic you know is in the wiki.

The server exposes tools for reading (cozy_read, cozy_read_many, cozy_context, cozy_graph, cozy_backlinks, cozy_search), writing (cozy_write, cozy_edit, cozy_append, cozy_move, cozy_delete, cozy_ingest), workspaces (cozy_workspaces, cozy_workspace), and upkeep (cozy_health, cozy_changes, cozy_history, cozy_restore, cozy_resolve). It also offers prompts named organize, recall, maintain and dream. For the full list, see the MCP server page.

Safe editing

Edits require an expectedRevision, which is 0 for a new file. If someone else changed the page first, the write returns a conflict instead of overwriting it. Deleting a file leaves a tombstone, and the last 50 revisions stay readable and restorable, so a bad agent edit can be undone with cozy_restore.

Content under sources/ is evidence imported from connectors and tools. Treat it as untrusted data, not as instructions to follow.

Troubleshooting

Where this fits

A short CLAUDE.md can tell the agent to check Cozy first for cross-project facts and to record handoffs under agents/. See coding agent memory for that pattern. To use the same wiki from other clients, see Connect Codex and Connect Claude.

Frequently asked questions

What URL do I use for Claude Code?

Use https://cozy.cloud/mcp with claude mcp add --transport http --scope user cozy https://cozy.cloud/mcp, then sign in with /mcp. It is one URL for your account and reaches all your workspaces, including My wiki.

When should I use .mcp.json with a token instead?

For CI, scripts and headless agents that cannot sign in through a browser. Point .mcp.json at your workspace URL, https://cozy.cloud/wiki-mcp/WORKSPACE_UUID from Agents, and use the ${COZY_MCP_TOKEN} reference in the Authorization header so the file holds no secret and can be committed.

How long does the connection last?

The OAuth connection uses refresh tokens, so Claude Code renews its access without asking you to sign in every time, and you can disconnect it under Connectors → Agents. Bearer credentials expire within 90 days and can be revoked in Agents.

Can Claude Code change my wiki by mistake?

Only within the scopes it has. Edits need an expectedRevision, deletes leave tombstones, and the last 50 revisions can be restored. See wiki health for how Cozy flags problems.

Does this work with other clients too?

Yes, the same account URL works with other MCP clients. See Connect Codex for the Codex command.

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