How to connect Codex to your Cozy wiki

Updated · By the Cozy team

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

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:

  1. The sign-in finished. Run codex mcp login cozy again if you are unsure.
  2. Codex is still listed under Connectors → Agents in Cozy. If you disconnected it there, sign in again.
  3. You approved the scope the tool needs. Write tools need wiki:write or sources: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:

ScopeWhat it allows
readRead pages, search, graph and health tools
wiki-writeWrite and edit curated wiki pages
source-writeWrite 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 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