Connect your agents
Connect Cursor and other MCP clients to Cozy
To connect Cursor to Cozy, click Add to Cursor on Cozy's Connectors page, or add {"mcpServers":{"cozy":{"url":"https://cozy.cloud/mcp"}}} to ~/.cursor/mcp.json. Cursor then runs an OAuth sign-in, you approve access on Cozy's consent page, and the agent can reach all your workspaces. For headless tools, a workspace URL with a bearer token is also available.
What you need before you start
Cozy hosts one MCP endpoint per account, https://cozy.cloud/mcp, for all your workspaces. It speaks stateless Streamable HTTP and accepts MCP protocol versions 2025-03-26, 2025-06-18 and 2025-11-25. Any client that can talk to a remote HTTP MCP server with OAuth can use it, which includes Cursor and most editors and agent tools that read an mcp.json style file.
You need a Cozy account and Cursor. There is no token to copy for the default setup.
If you are new to the product, Cozy is a private wiki and cloud file space for each person and their AI agents. The MCP server page covers what the endpoint exposes in more depth.
Option 1: Add to Cursor
- Sign in to Cozy and open Connectors → Agents.
- Click Add to Cursor and follow Cursor's prompt to add the
cozyserver. - Confirm, then sign in to Cozy and approve access on the consent page.
Option 2: Edit mcp.json
Add this to ~/.cursor/mcp.json, or merge it into the file if it already exists:
{
"mcpServers": {
"cozy": {
"url": "https://cozy.cloud/mcp"
}
}
}
There is no Authorization header. Cursor starts the OAuth sign-in the first time it connects. Cursor's UI and file locations may change, so treat its own documentation as the authority for those details.
How the OAuth connection works
Cozy uses OAuth 2.1 with dynamic client registration, S256 PKCE and refresh tokens, so Cursor registers itself and renews its access without asking you to sign in every time. The scopes are wiki:read, wiki:write and sources:write. Cursor's access is capped by the scopes you approved and by your own access, checked on every request, so it cannot do more than you can.
Every tool takes an optional workspace argument, a workspace ID or exact name. Without it, tools use My wiki. cozy_workspaces lists the workspaces the agent can reach.
Connected agents are listed under Connectors → Agents in Cozy, where you can disconnect Cursor at any time. The same page has Add to Claude and Add to VS Code buttons for those clients.
For headless tools: a workspace URL and bearer token
Scripts, CI jobs and tools that cannot run a browser sign-in can use a workspace endpoint instead. It has the form https://cozy.cloud/wiki-mcp/WORKSPACE_UUID and is shown under Agents in the app. It accepts a bearer credential:
- You create it in Agents. It is random and shown once, and Cozy stores only a SHA-256 digest.
- It is revocable, expires within 90 days, and carries scopes: read, wiki-write and source-write.
- You can restrict it to folder prefixes, such as a single project folder.
- It reaches only that workspace, and its scopes never exceed your own access.
Cursor expands environment variables written as ${env:NAME} in mcp.json, so a bearer entry looks like this:
{
"mcpServers": {
"cozy": {
"url": "https://cozy.cloud/wiki-mcp/WORKSPACE_UUID",
"headers": {
"Authorization": "Bearer ${env:COZY_MCP_TOKEN}"
}
}
}
}
Replace WORKSPACE_UUID with the value from Agents and set COZY_MCP_TOKEN in the environment that launches the client. Other clients differ in where the config file lives, whether a type field is required, and whether and how they expand environment variables in headers. If a client does not expand them, you may need to paste the token into the file, so keep that file out of version control. OAuth on a workspace URL also still works, but it grants only that workspace.
If a token leaks, revoke it in Agents. Agents cannot see connector credentials or permanently purge, whatever scopes they have.
Check that it works
After connecting, look for the cozy server in Cursor's MCP settings and confirm it shows as connected. Then ask the agent to call cozy_workspaces, which lists your workspaces. Try cozy_map for an index grouped by type, or cozy_search for a lexical search with cursor paging.
Cozy also exposes file resources, resource templates and prompts named organize, recall, maintain and dream. Which of these a given client surfaces depends on that client's MCP support.
Common problems:
- A sign-in prompt that keeps coming back usually means the agent was disconnected under Connectors → Agents. Sign in again.
- A 401 on a workspace URL usually means a missing, expired or revoked token, or an environment variable that the client did not expand.
- Writes that fail while reads work usually mean you approved only the read scope, the credential has only read.
- Edits require an expected revision, 0 for a new file. A conflict means someone else saved first, so re-read and retry.
Other clients
The same account URL works in other tools. For Codex, run codex mcp add cozy --url https://cozy.cloud/mcp; the Codex guide has the details. For Claude Code, run claude mcp add --transport http --scope user cozy https://cozy.cloud/mcp and sign in with /mcp; the Claude Code guide walks through it. In Claude's connector settings, add a custom connector with the same URL.
Cursor users often want repo-aware memory for coding sessions. See coding agent memory for how agents use the agents/ folder for notes and handoffs.
What Cozy does not do
Cozy runs no model itself, so you bring your own agent, whether that is Cursor or something else. Search is lexical, with no embeddings or vector database. Competitors may fit better if you want semantic search or a fully local, stdio-based setup. Cozy is hosted on Cloudflare and operated by Coral Sourcing LLC. It is not affiliated with Cozy Cloud (cozy.io) or Cozi.
Frequently asked questions
Does Cozy work with Cursor?
Yes. Click Add to Cursor on Cozy's Connectors page, or add {"mcpServers":{"cozy":{"url":"https://cozy.cloud/mcp"}}} to ~/.cursor/mcp.json, then sign in with OAuth when Cursor asks.
Do I need a bearer token for Cursor?
No. The account URL uses OAuth, so there is nothing to copy. Bearer tokens are for scripts and headless tools that use a workspace URL. Create one under Agents; it is shown once, expires within 90 days and can be revoked at any time.
Should I use OAuth or a bearer header?
Use OAuth with https://cozy.cloud/mcp for Cursor and other interactive clients; it reaches all your workspaces. Use a bearer header with a workspace URL for a fixed credential in a script or CI job, optionally limited to folder prefixes.
Can a token do more than my account can?
No. Cozy caps an agent's access at the scopes it was granted and your own access, and agents cannot see connector credentials or permanently purge. See the MCP server page for the tool list.
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