# Connect Cursor and other MCP clients to Cozy

> Add a remote Streamable HTTP MCP server to Cursor or any MCP client with an mcp.json entry and an Authorization bearer header. Includes the Cozy workspace URL and token setup.

Updated 2026-11-09. Canonical: https://cozy.cloud/connect/cursor

> 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](/mcp-server) 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:

```json
{
  "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:

```json
{
  "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](/connect/codex) 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](/connect/claude-code) 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](/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](/mcp-server) for the tool list.
