Codex CLI and Local Setup

Use The Shared Plugin For Managed Fluent

For the normal managed setup, use Connecting to ChatGPT + Codex. Add Fluent once through OpenAI's shared plugin library, then start a new Codex task with @Fluent.

This page is only for developers who specifically want Codex CLI MCP commands, generated configuration, the repo-local Fluent bundle, or the open-source runtime.

Codex CLI

Add the managed Fluent MCP server and authenticate:

codex mcp add fluent --url https://mcp.meetfluent.app/mcp
codex mcp login fluent

Complete Fluent sign-in in the browser, then check the connection with codex mcp list.

For first-recovery fixes, see Connect Fluent troubleshooting.

What this page covers

This page is the technical setup guide for local and CLI use with Codex.

You still work in Codex directly. Fluent is the MCP server Codex uses for structured context and tools.

For the plain-language overview first, start here:

• Using Fluent with AI Apps

Managed Fluent is currently free. You can also run the open-source version yourself.

Codex can also use Fluent through MCP server settings, .mcp.json configuration files, or the repo-local plugin bundle. These are technical alternatives to the shared OpenAI plugin installation, not an additional step after it.

Advanced: scaffold generator

Use this path only if you have the Fluent repository checked out -- otherwise follow the hosted quick start above.

The scaffold generator is useful when you need checked-in plugin files, generated config, or open-source runtime setup.

Early access

npm run scaffold:mcp -- --client codex --track cloud

Use this for managed Fluent. To host Fluent yourself, use the open-source setup below.

Run Fluent yourself

npm run scaffold:mcp -- --client codex --track oss \
  --base-url http://127.0.0.1:8788

The generator resolves the local token automatically from ~/.fluent/ unless you provide --token or --root.

Write directly to plugin directory

npm run scaffold:mcp -- --client codex --track oss \
  --base-url http://127.0.0.1:8788 \
  --out plugins/fluent/.mcp.json

Repo-local plugin structure

The Fluent bundle for repo-local Codex installation lives at plugins/fluent/ and includes these key assets:

File	Purpose
.codex-plugin/plugin.json	Plugin metadata
.mcp.json	Default managed-endpoint MCP config template
.mcp.hosted.json	Managed-endpoint compatibility template
.mcp.oss.json	Open-source runtime template
.mcp.local.json	Local open-source runtime template

Install the plugin from the plugins/fluent/ directory, not from .codex-plugin/.

Manual self-hosted setup

Use this path only if you have the Fluent repository checked out -- otherwise follow the hosted quick start above.

If you prefer to configure the open-source runtime manually:

1. Start the open-source runtime:

npm run oss:start -- --host 127.0.0.1 --port 8788

2. Print your token:

npm run oss:token:print

3. Run the scaffold generator:

npm run scaffold:mcp -- --client codex --track oss \
  --base-url http://127.0.0.1:8788

4. Reconnect Codex so it refreshes the MCP registration and tool schema.

Reconnect an older registration

If Codex was connected to an older registration, reconnect and re-authorize. Fluent expects these scopes on the active grant:

• meals:read
• meals:write
• style:read
• style:write
• offline_access

Verifying the connection

Ask Codex:

"What can Fluent help me with?"

Codex should summarize what Fluent can do with your current setup and suggest a useful next step.

Start here after setup

Once Fluent is connected, use Codex directly:

"What can Fluent already help me with right now, and what should we set up first?"

Then move into one of the domain entrypoints:

"Plan next week around my schedule and turn it into a grocery list I can actually shop from."

Minimum contract version

The Codex plugin expects:

• Minimum contract version: 2026-07-09.fluent-core-v2.0

Troubleshooting

See Connect Fluent troubleshooting for the shared first recovery steps.

Tools not appearing

• Reconnect the MCP server in Codex
• If you run Fluent yourself, verify Fluent is running: curl http://127.0.0.1:8788/health
• Check your .mcp.json has the correct base URL and token

Stale tools after endpoint change

1. Reconnect the MCP server
2. Re-authorize if prompted
3. Remove stale credentials for the old endpoint if Codex keeps surfacing the previous tool set

Codex probe

The open-source runtime exposes a GET /codex-probe endpoint that Codex uses for compatibility checks:

curl http://127.0.0.1:8788/codex-probe