Guides
Cozy MCP server for Claude, Codex and ChatGPT
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
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, choose + and then Add custom MCP server. Name it Cozy, paste https://cozy.cloud/mcp and sign in.
Connect Claude Code
claude mcp add --transport http --scope user cozy https://cozy.cloud/mcp
Then run /mcp inside Claude Code and sign in.
Connect Codex
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:
{ "mcpServers": { "cozy": { "url": "https://cozy.cloud/mcp" } } }
Per-workspace endpoints for scripts and CI
Each workspace also has its own endpoint:
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:
{
"mcpServers": {
"cozy": {
"type": "http",
"url": "https://cozy.cloud/wiki-mcp/WORKSPACE_UUID",
"headers": { "Authorization": "Bearer ${COZY_MCP_TOKEN}" }
}
}
}
In Codex's config.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:
---
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.
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.
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