Connecting to Codex

This page is the technical setup guide for using Fluent with Codex.

If you want the plain-language overview first, start here:

• Using Fluent with AI Apps

Today, the documented path is Fluent OSS. Fluent Cloud setup docs will be published when the cloud product is ready.

Codex discovers Fluent through .mcp.json configuration files.

Scaffold Generator

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

Fluent OSS

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

The generator resolves the OSS 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 Fluent Codex plugin lives at plugins/fluent/ and contains:

File	Purpose
.codex-plugin/plugin.json	Plugin metadata
.mcp.json	Default MCP config template
.mcp.oss.json	OSS template
.mcp.local.json	Legacy bridge asset

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

Manual Setup (OSS)

If you prefer to configure manually:

1. Start Fluent OSS:

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.

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.

Minimum Contract Version

The Codex plugin expects:

• Minimum contract version: 2026-04-05.fluent-core-v1.31

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

Fluent OSS exposes a GET /codex-probe endpoint that Codex uses for compatibility checks:

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