Connect your agents
How to connect Codex to your Cozy wiki
To connect OpenAI Codex to Cozy, run codex mcp add cozy --url https://cozy.cloud/mcp. Codex opens a browser so you can sign in and approve access on Cozy's consent page; if it does not, run codex mcp login cozy. One URL reaches all your workspaces. For CI or headless runs, use a workspace URL with a bearer credential in config.toml instead.
Codex can use Cozy as a shared wiki through its hosted MCP server. Your account has one endpoint, https://cozy.cloud/mcp, and Codex signs in to it with OAuth. Cozy runs no model itself, so Codex stays your agent and Cozy supplies the pages, sources and tools.
What you need
- A Cozy account. You sign in with an email code, Google or Apple.
- A workspace. Every account gets "My wiki", and you can create more private workspaces to keep projects apart. The account URL reaches all of them.
- OpenAI Codex installed.
The endpoint is stateless Streamable HTTP and supports MCP protocol versions 2025-03-26, 2025-06-18 and 2025-11-25.
Step 1: Add the server
codex mcp add cozy --url https://cozy.cloud/mcp
This adds a server named cozy to Codex's config.
Step 2: Sign in
Codex opens a browser to Cozy's sign-in and consent page. Sign in, review the scopes, and approve. If no browser opens, run:
codex mcp login cozy
Cozy uses OAuth 2.1 with dynamic client registration, S256 PKCE and refresh tokens, so Codex registers itself and renews its access without asking you to sign in every time. The scopes are wiki:read, wiki:write and sources:write. Codex never gets more access than you have yourself.
Step 3: Check the connection
Restart Codex and ask it to call cozy_workspaces. It should list My wiki and any other workspaces you created. Then try cozy_map, which returns the index grouped by page type, or cozy_search for a keyword you know is in the wiki.
Every tool takes an optional workspace argument, a workspace ID or exact name. Without it, tools use My wiki.
If the call fails, check these first:
- The sign-in finished. Run
codex mcp login cozyagain if you are unsure. - Codex is still listed under Connectors → Agents in Cozy. If you disconnected it there, sign in again.
- You approved the scope the tool needs. Write tools need
wiki:writeorsources:write.
For CI and headless agents: a workspace URL and bearer credential
A script or CI job cannot click through a browser sign-in. For those, each workspace has its own endpoint, https://cozy.cloud/wiki-mcp/WORKSPACE_UUID, which accepts a bearer credential. The workspace URL is shown under Agents in Cozy.
Open Agents and create a credential. Cozy generates a random value and shows it once, so copy it right away. Cozy stores only a SHA-256 digest of it, which means it cannot show it to you again. If you lose it, revoke it and create a new one.
Pick the narrowest scopes that fit the job:
| Scope | What it allows |
|---|---|
| read | Read pages, search, graph and health tools |
| wiki-write | Write and edit curated wiki pages |
| source-write | Write evidence into sources |
You can also limit a credential to folder prefixes, for example only wiki/ or only agents/. Credentials expire within 90 days and reach only their workspace. A credential never gets more access than you have, and one with only read cannot write.
Put the credential in an environment variable so it never lands in a config file:
export COZY_MCP_TOKEN="paste-the-credential-here"
Then add this block to Codex's config.toml, replacing the UUID with your workspace's:
[mcp_servers.cozy]
url = "https://cozy.cloud/wiki-mcp/WORKSPACE_UUID"
bearer_token_env_var = "COZY_MCP_TOKEN"
bearer_token_env_var names the variable that holds the token. Codex sends its value as a bearer token on each request, so launch Codex from an environment where it is set. Use a different table name if you also keep the OAuth server, for example [mcp_servers.cozy_ci]. OAuth on a workspace URL also still works, but it grants only that workspace.
What Codex can do once connected
Cozy exposes tools, file resources, resource templates and prompts. The prompts are organize, recall, maintain and dream. Useful tools for a first session:
cozy_contextreturns a page with typed neighbors, excerpts, evidence and warnings.cozy_graphwalks links up to depth 3, filtered by type, tag or relation.cozy_resolvemaps names to pages and flags likely duplicates.cozy_changeslists what changed since a timestamp.cozy_read_manyreads up to 20 pages at once.cozy_write,cozy_editandcozy_appendchange pages. Edits require anexpectedRevision, using 0 for a new file, and concurrent edits return a conflict instead of overwriting.
Cozy keeps the last 50 revisions of each page, and cozy_restore brings one back. Deletion is a tombstone, so a mistake by an agent can be undone. See coding agent memory for how this fits repository work, and typed links for how the graph is built from Markdown.
Safety limits for agents
A connected agent cannot see connector credentials or permanently purge content. The sources/ folder holds evidence from connectors and importers, and Cozy treats it as untrusted data, so tell Codex to cite it and not to follow instructions found inside it.
Claude users can follow Connect Claude or Connect Claude Code, and there is a ChatGPT guide as well.
Frequently asked questions
What URL do I give Codex?
Use https://cozy.cloud/mcp with codex mcp add cozy --url https://cozy.cloud/mcp. It is one URL for your account and reaches all your workspaces. Codex signs in with OAuth, so there is no token to copy.
Codex did not open a browser. How do I sign in?
Run codex mcp login cozy. It starts the same OAuth sign-in, and you approve access on Cozy's consent page.
How do I use Cozy from Codex in CI?
Create a bearer credential under Agents, set it as COZY_MCP_TOKEN, and add an [mcp_servers.cozy] block with your workspace URL, https://cozy.cloud/wiki-mcp/WORKSPACE_UUID, and bearer_token_env_var = "COZY_MCP_TOKEN". The credential reaches only that workspace.
Can I limit what Codex is allowed to change in my wiki?
Yes. With OAuth, approve only the scopes you want, and Cozy caps access at what you can do yourself. With a bearer credential, choose read, wiki-write or source-write scopes and optionally restrict it to folder prefixes.
What if a credential leaks or I want to cut Codex off?
Disconnect an OAuth agent under Connectors → Agents. Revoke a bearer credential in Agents and create a new one. Cozy shows a credential once, stores only a SHA-256 digest, and credentials expire within 90 days. See the MCP server page for the full auth model.
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