Connecting to Codex

This page is the technical setup guide for using Fluent 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

Fluent is in early access and open source. Use managed early access for the hosted path, or run Fluent yourself to inspect, self-host, or build with the open-source runtime.

Codex discovers Fluent through .mcp.json configuration files.

Scaffold Generator

The preferred way to set up Codex is the scaffold generator.

Early Access

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

Use this for early-access setups after your account has been provisioned. To use Fluent immediately, run the open-source runtime yourself.

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

Codex Plugin Structure

The mirrored Fluent Codex bundle 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	Legacy managed-endpoint compatibility template
.mcp.oss.json	Open-source runtime template
.mcp.local.json	Legacy bridge asset

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

Manual Setup

If you prefer to configure 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.

Early Access Reconnects

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

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

Verifying the Connection

Ask Codex:

"What are my Fluent capabilities?"

Codex will call fluent_get_capabilities and return your contract version, domains, and profile state.

Start Here

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-04-20.fluent-core-v1.37

Troubleshooting

Tools not appearing

• Reconnect the MCP server in Codex
• 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