# Cozy MCP server for Claude, Codex and ChatGPT

> Connect Claude, Claude Code, Codex, ChatGPT and other MCP clients to a hosted Markdown knowledge base with typed links, lint, source citations, scoped credentials and restorable history.

Updated 2026-11-09. Canonical: https://cozy.cloud/mcp-server

> Cozy is a hosted remote MCP server for a private Markdown wiki. Every account has one Streamable HTTP endpoint, `https://cozy.cloud/mcp`, that reaches all your workspaces. Clients sign in with OAuth 2.1, then search, read, link, create, update, move, delete and restore files. Scripts and headless agents can use a per-workspace endpoint with a scoped bearer credential instead.

## Endpoint

```text
https://cozy.cloud/mcp
```

This is the same URL for everyone. Clients connect with OAuth 2.1: dynamic client registration, PKCE with S256 and refresh tokens. You approve the agent on Cozy's consent page, choosing the scopes it gets: `wiki:read`, `wiki:write` and `sources:write`. The server speaks Streamable HTTP and supports MCP protocol versions 2025-03-26, 2025-06-18 and 2025-11-25. It exposes tools, file resources, resource templates and four prompts: organize, recall, maintain and dream.

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 use.

Connected agents are listed under **Connectors → Agents** in the Cozy app, where you can disconnect them. The same page has one-click **Add to Claude**, **Add to Cursor** and **Add to VS Code** buttons.

## Connect Claude

In Claude, open Settings (or Customize), then **Connectors**, choose **Add custom connector** and paste `https://cozy.cloud/mcp`. Approve access on the Cozy consent page.

## Connect ChatGPT

Open [chatgpt.com/plugins](https://chatgpt.com/plugins), choose **+** and then **Add custom MCP server**. Name it Cozy, paste `https://cozy.cloud/mcp` and sign in.

## Connect Claude Code

```bash
claude mcp add --transport http --scope user cozy https://cozy.cloud/mcp
```

Then run `/mcp` inside Claude Code and sign in.

## Connect Codex

```bash
codex mcp add cozy --url https://cozy.cloud/mcp
```

Codex opens a browser to sign in. If it does not, run `codex mcp login cozy`.

## Connect Cursor

Use **Add to Cursor** on Cozy's Connectors page, or add this to `~/.cursor/mcp.json`:

```json
{ "mcpServers": { "cozy": { "url": "https://cozy.cloud/mcp" } } }
```

## Per-workspace endpoints for scripts and CI

Each workspace also has its own endpoint:

```text
https://cozy.cloud/wiki-mcp/WORKSPACE_UUID
```

Use it for scripts, CI and headless agents that cannot complete a browser sign-in. Create a workspace credential under **Agents** with the read, wiki-write or source-write scopes it needs and optional folder prefixes, export it as `COZY_MCP_TOKEN`, and send it as a bearer token. In Claude Code's `.mcp.json`:

```json
{
  "mcpServers": {
    "cozy": {
      "type": "http",
      "url": "https://cozy.cloud/wiki-mcp/WORKSPACE_UUID",
      "headers": { "Authorization": "Bearer ${COZY_MCP_TOKEN}" }
    }
  }
}
```

In Codex's `config.toml`:

```toml
[mcp_servers.cozy]
url = "https://cozy.cloud/wiki-mcp/WORKSPACE_UUID"
bearer_token_env_var = "COZY_MCP_TOKEN"
```

Keep tokens in the client's environment or secret manager, never in shared configuration. OAuth on a workspace URL also still works, but it grants only that workspace.

## Tools

| Tool | What it does |
| --- | --- |
| `cozy_context` | One-call recall: a page, its typed neighbors with excerpts, its evidence and warnings |
| `cozy_search`, `cozy_list` | Search paths, titles and full content, and browse folders, with pagination |
| `cozy_read`, `cozy_read_many` | Read a file or a retained revision, or up to 20 files at once |
| `cozy_graph` | Traverse the knowledge graph up to depth 3, filtered by type, tag or relation |
| `cozy_backlinks`, `cozy_resolve` | Find incoming links, map names to pages and spot likely duplicates |
| `cozy_health` | Score the wiki and list broken links, stale pages, conflicts and orphans in priority order |
| `cozy_changes` | Files changed since a timestamp, for consolidation runs |
| `cozy_map` | Generate an index grouped by type for `wiki/index.md` |
| `cozy_history`, `cozy_restore` | Inspect and restore any of the last 50 revisions |
| `cozy_ingest` | Save evidence into `sources/` |
| `cozy_workspaces` | List the workspaces you can use, to pass as `workspace` to other tools |
| `cozy_workspace`, `cozy_skills` | Identify the workspace and its grants, and discover workspace skills |
| `cozy_write`, `cozy_edit`, `cozy_append` | Create pages, apply revision-checked edits and append to existing pages |
| `cozy_move`, `cozy_delete` | Move a page (returning links to repair) or delete it to a restorable tombstone |

Write tools require the `wiki:write` or `sources:write` scope, or a workspace credential with wiki-write or source-write.

## Permissions and safety

- An agent never gets more access than you have in each workspace, capped by the scopes it was granted. Both are checked on every request.
- Connected agents can be disconnected at any time under **Connectors → Agents**.
- Workspace credentials are random, stored as SHA-256 digests, shown once, revocable and expire within 90 days. Their scopes are read, wiki-write and source-write, with optional folder prefixes, and never exceed your own access.
- Every edit carries an `expectedRevision`. A stale edit returns a conflict instead of overwriting.
- Deletes create tombstones and the last 50 revisions stay restorable. Agents cannot permanently purge content.
- Imported sources are treated as untrusted evidence, and agents are told to ignore instructions inside them.

## What agents can write

Pages are portable Markdown. Agents add structure with conventions they already know:

```markdown
---
type: project
description: The billing rewrite. Read before changing invoices.
aliases: [Billing v2]
---
# Billing

- depends_on:: [[wiki/projects/api.md]]
- decided_in:: [[Kickoff 2026-11-04]]
Ann owns the rollout. [[sources/files/kickoff-notes.md]]
```

Read more about the model in [what a personal knowledge graph is](/personal-knowledge-graph).

## Frequently asked questions

### What is the best MCP server for a knowledge base?

For a knowledge base your agents maintain, choose a hosted server with remote access, plain portable files, conflict-safe writes, restorable history and scoped credentials. Cozy provides all of these, with one endpoint for all your workspaces.

### Does Cozy work with ChatGPT?

Yes. Add https://cozy.cloud/mcp as a custom MCP server and sign in with OAuth. Which ChatGPT plans can use write-capable custom connectors is set by OpenAI. Read access works with read-only connectors.

### Does Cozy need embeddings or a vector database?

No. Cozy search is lexical over paths, titles and full content, and structure comes from links and frontmatter. There is no embedding requirement.
