# How to connect Codex to your Cozy wiki

> Add Cozy to OpenAI Codex as an MCP server: create a bearer credential in Agents, set bearer_token_env_var in config.toml, and check the connection with cozy_workspace.

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

> 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](/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

```bash
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:

```bash
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:

| 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:

```bash
export COZY_MCP_TOKEN="paste-the-credential-here"
```

Then add this block to Codex's `config.toml`, replacing the UUID with your workspace's:

```toml
[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_context` returns a page with typed neighbors, excerpts, evidence and warnings.
- `cozy_graph` walks links up to depth 3, filtered by type, tag or relation.
- `cozy_resolve` maps names to pages and flags likely duplicates.
- `cozy_changes` lists what changed since a timestamp.
- `cozy_read_many` reads up to 20 pages at once.
- `cozy_write`, `cozy_edit` and `cozy_append` change pages. Edits require an `expectedRevision`, 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](/coding-agent-memory) for how this fits repository work, and [typed links](/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](/connect/claude) or [Connect Claude Code](/connect/claude-code), and there is a [ChatGPT guide](/connect/chatgpt) 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](/mcp-server) for the full auth model.
