Clear Ideas + Codex via MCP

OpenAI Codex supports Model Context Protocol (MCP), which means you can connect Codex directly to your Clear Ideas sites. Once connected, Codex can use MCP tools to list sites, search content, retrieve context, and save files — all grounded in the same secure data and analytics you use in Clear Ideas.

In this article, we’ll:

Create an MCP access key in Clear Ideas.
Configure Codex to connect to the Clear Ideas via MCP.
Use environment variables to keep your bearer token out of config files.
Show how the unified “Release v3.2” workflow from Part 2 works inside Codex.

For a governance and analytics overview, see Part 1: Personal MCP Access Keys + Analytics. For the full end‑to‑end workflow example shared across all hosts, see Part 2: Cursor + Clear Ideas via MCP.

1. Prerequisites

You’ll need:

A Clear Ideas account with permission to create MCP access keys.
OpenAI Codex installed and authenticated (CLI or IDE extension).
MCP enabled in your Codex config (this is on by default for current versions).

Codex stores MCP configuration in ~/.codex/config.toml, which is shared between the CLI and IDE extension.

2. Create an MCP Access Key in Clear Ideas

In Clear Ideas, go to Settings → Access Keys.
Click New Access Key.
Choose MCP as the key type.
Select scopes:
- mcp:read for read-only use (listing sites, searching content, retrieving context, viewing versions and diffs).
- mcp:write if you want to create files/folders or save new document versions.
(Optional) Set an expiration date.
Copy the key value — this is your MCP bearer token.

Under the hood, Codex will send this token as:

Authorization: Bearer YOUR_MCP_ACCESS_KEY

3. Store Your Token in an Environment Variable

To avoid hard‑coding secrets into config.toml, we’ll store the token in an environment variable and let Codex read it when connecting to the MCP HTTP server.

On Mac/Linux:

export CLEARIDEAS_MCP_ACCESS_KEY="mcp-your-access-key-here"

You can add this line to your shell profile (e.g., ~/.zshrc or ~/.bashrc) so it’s set automatically for future sessions.

4. Register Clear Ideas as an MCP Server in Codex

You have two options: use the Codex CLI helper, or edit config.toml directly.

Option A: Use the Codex CLI

From the Codex docs, MCP HTTP servers can be registered with --url and a --bearer-token-env-var that points to your environment variable.

Run:

codex mcp add clearideas   --url https://api.clearideas.com/mcp   --bearer-token-env-var CLEARIDEAS_MCP_ACCESS_KEY

This tells Codex:

Use https://api.clearideas.com/mcp as a streamable MCP HTTP endpoint.
When connecting, read the bearer token from the CLEARIDEAS_MCP_ACCESS_KEY environment variable.

You can confirm the configuration with:

codex mcp list

You should see clearideas listed as an enabled MCP server.

Option B: Edit `config.toml` Directly

If you prefer to manage configuration by hand, open ~/.codex/config.toml and add:

[mcp_servers.clearideas]
command = "npx"
args = ["-y", "clearideas-mcp"]
env = { "CLEARIDEAS_MCP_ACCESS_KEY" = "key", "CLEARIDEAS_MCP_URL" = "https://api.clearideas.local/mcp" }

This is the TOML equivalent of the CLI command above. Codex will inject the value from your environment variable into the Authorization: Bearer … header whenever it talks to the Clear Ideas MCP server.

5. Using Clear Ideas MCP Tools from Codex

Once configured, Codex can call the same Clear Ideas MCP tools as Cursor and Claude Code, including:

clearideas.list_sites
clearideas.list_content
clearideas.search_content
clearideas.retrieve_context
clearideas.retrieve_context_for_file
clearideas.retrieve_diff_for_file
clearideas.save_file
clearideas.create_folder

List Sites

From the Codex CLI, you might start with:

codex

Then, in the Codex prompt:

Use clearideas.list_sites to show which Clear Ideas sites I can access.

Codex will call clearideas.list_sites through MCP and show a list of sites and IDs, for example:

Due Diligence – Company X – siteId: abcd1234
Release v3.2 – Logs & Dashboards – siteId: efgh5678

Run the Unified “Release v3.2” Workflow

In Part 2, we showed how an MCP host can:

Use clearideas.search_content to find log or performance files for a release.
Use clearideas.retrieve_context to pull the most relevant chunks.
Generate a “Release v3.2 – Post‑Deployment Report” in Markdown.
Save the report with clearideas.save_file.
Later, use clearideas.retrieve_diff_for_file to compare versions (for example, “now” vs. “one week ago”).

You can ask Codex to run the same workflow, grounded in the MCP tools:

In the "Release v3.2 – Logs & Dashboards" site, use clearideas.search_content and clearideas.retrieve_context to analyze error rates and latency. Draft a Markdown report I can share with leadership, then save it back into that site with clearideas.save_file. Finally, show me a diff between the current version and the version from one week ago using clearideas.retrieve_diff_for_file.

Codex will orchestrate the tool calls, show intermediate results if you ask, and keep everything stored — and versioned — inside Clear Ideas.

6. Why Codex + Clear Ideas Is Powerful

Codex excels at agentic coding workflows in the terminal or IDE: inspecting repos, editing files, and running commands. By adding Clear Ideas via MCP, you extend that workflow into your organization’s reference material:

Pull contracts, runbooks, product docs, or logs as context.
Let Codex synthesize findings alongside your code.
Save outputs directly into Clear Ideas where non‑technical stakeholders can read, search, and audit them.

Because MCP calls flow through Clear Ideas, all actions are logged and controlled just like activity in the Clear Ideas UI. Site owners keep control over which sites are accessible, and analytics still show who did what, when.

7. Try It Now

If you already use Codex:

Create an MCP access key in Clear Ideas with mcp:read (and mcp:write if you need it).
Export CLEARIDEAS_MCP_ACCESS_KEY in your shell.
Register the MCP server with codex mcp add clearideas --url https://api.clearideas.com/mcp --bearer-token-env-var CLEARIDEAS_MCP_ACCESS_KEY.
Run through the Release v3.2 workflow from Part 2 inside Codex.