Connect Cursor and other MCP clients to Cozy

Updated · By the Cozy team

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

  1. Sign in to Cozy and open Connectors → Agents.
  2. Click Add to Cursor and follow Cursor's prompt to add the cozy server.
  3. 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:

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:

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