Skip to main content
ACE3 LogoACE3

ChatGPT / Codex CLI Setup

Configure ACE MCP with OpenAI's ChatGPT and Codex CLI tools - Complete step-by-step guide.

Prerequisites
1

Node.js 18+ installed

Check with: node --version

2

OpenAI Codex CLI installed

3

OpenAI API key configured

Get API key from OpenAI →

4

ACE CLI installed and configured

5

ACE server running

MCP Support in Codex CLI

OpenAI's Codex CLI supports MCP (Model Context Protocol) for connecting to external tools like ACE3. This allows ChatGPT/GPT-4 models to access your project's cognitive infrastructure for persistent context.

1
Create MCP Config File

Create the MCP configuration file at the appropriate location for your operating system:

Config file location (TOML format):

The config file is created when you first run codex

2
Add ACE Configuration

Add the ACE MCP server to your file (TOML format): config.toml

Or use to configure automatically. ace mcp setup

Tip: Automatic Setup

Run and it will automatically configure MCP for Codex CLI. ace init

3
Run Codex CLI

Start the Codex CLI in your project directory:

4
Test ACE Integration

Try these prompts to test the ACE integration:

Store a memory:

"Store this memory: the project uses React 18 with TypeScript"

Track a decision:

"What decisions have been made about the database?"

Track an issue:

"Create an issue for the performance regression in the API"

Success!

If Codex responds by using ACE tools, your setup is complete!

Alternative: Direct REST API

If MCP is not available or you're using ChatGPT web interface, you can use ACE's REST API directly:

You can create custom GPT actions that call these API endpoints for ChatGPT Plus/Pro users.

Troubleshooting

"ace: command not found"

The ACE CLI is not in your PATH. Try these fixes:

  1. Reinstall ACE globally: npm install -g @ace3-memory/ace
  2. Check if npm global bin is in PATH: npm bin -g
  3. Add npm global bin to your PATH in
ACE tools not appearing
  1. Verify ACE server is running: ace status
  2. Check config file for JSON syntax errors
  3. Restart Codex CLI after config changes
  4. Verify the config file path is correct
"Connection refused" errors
  1. Start ACE server: ace start
  2. Check health: curl http://localhost:7777/health
  3. Check if port 7777 is blocked by firewall

Available ACE Tools

Once configured, Codex CLI can use all 77 ACE tools:

ace_remember
ace_recall
ace_get_context
ace_search
ace_track_issue
ace_resolve_issue
ace_find_solutions
ace_track_decision
ace_best_practices
ace_get_stats
ace_log_work
ace_architecture
ace_patterns
ace_manage_tags
ace_graph_traverse
ace_graph_connect
ace_graph_related
ace_graph_list
ace_graph_health
ace_graph_analytics
ace_save_plan
ace_list_plans
ace_get_plan
ace_update_plan_task
ace_batch_create
ace_observe
ace_review_observations
ace_trigger_learning
ace_agent_status
ace_trigger_agent
ace_agent_config
ace_agent_history
ace_agent_activity
ace_agent_insights
ace_agent_health
ace_list_namespaces
ace_set_namespace
ace_create_namespace
ace_get_current_namespace