Troubleshooting Guide

This guide helps you resolve common issues with Codex MCP Tool.

Quick Diagnostics

Run these commands to check your setup:

# Check Codex CLI installation
codex --version

# Check Node.js version
node --version

# Check npm installation
npm list -g @trishchuk/codex-mcp-tool

# Test MCP connection (in Claude)
/codex-cli:ping "test"

Common Issues

Installation Issues

"Command not found: codex"

Problem: Codex CLI is not installed or not in PATH.

Solution:

# Install Codex CLI
curl -sSL https://codex.openai.com/install | bash

# Or via npm
npm install -g codex-cli

# Verify installation
codex --version

"Cannot find module '@trishchuk/codex-mcp-tool'"

Problem: The MCP tool is not installed correctly.

Solution:

# For Claude Code
claude mcp add codex-cli -- npx -y @trishchuk/codex-mcp-tool

# For global installation
npm install -g @trishchuk/codex-mcp-tool

# Verify installation
npm list -g @trishchuk/codex-mcp-tool

Connection Issues

"MCP server not responding"

Problem: The MCP server fails to start or connect.

Solutions:

1. Check configuration syntax:

{
  "mcpServers": {
    "codex-cli": {
      "command": "npx",
      "args": ["-y", "@trishchuk/codex-mcp-tool"]
    }
  }
}

2. Restart your MCP client:

• Claude Desktop: Quit and restart the application
• Claude Code: Run /restart command

3. Check server logs:

# Enable debug mode
DEBUG=codex-mcp:* npx @trishchuk/codex-mcp-tool

"Authentication failed"

Problem: Codex CLI is not authenticated.

Solution:

# Authenticate Codex CLI
codex auth login

# Verify authentication
codex auth status

# If needed, set API key
export OPENAI_API_KEY="your-api-key"

Tool Execution Issues

"Permission denied" errors

Problem: Insufficient permissions for file operations.

Solutions:

1. Adjust sandbox mode:

{
  "prompt": "analyze @src/",
  "sandboxMode": "workspace-write"  // Allow writes in workspace
}

2. Check file permissions:

# Check file permissions
ls -la /path/to/file

# Fix permissions if needed
chmod 644 file.txt

"Model not available"

Problem: Requested model is not accessible.

Solutions:

1. Check available models:

codex models list

2. Use fallback model:

{
  "prompt": "your prompt",
  "model": "gpt-5.1-codex-mini"  // Use available model
}

"Timeout exceeded"

Problem: Operation takes too long to complete.

Solutions:

1. Break down large tasks:

// Instead of analyzing entire codebase
'analyze @src/';

// Analyze specific directories
'analyze @src/utils/';
'analyze @src/components/';

2. Increase timeout (if configurable):

{
  "prompt": "complex task",
  "timeout": 300000  // 5 minutes
}

File Reference Issues

"File not found" with @ syntax

Problem: File references not resolving correctly.

Solutions:

1. Use correct path format:

// Correct formats
'@src/main.ts'; // Single file
'@src/*.ts'; // Glob pattern
'@src/**/*.ts'; // Recursive glob

// Incorrect formats
'@/src/main.ts'; // Don't use leading slash
'@~/src/main.ts'; // Don't use home directory shortcut

2. Check working directory:

# Verify current directory
pwd

# Run from project root
cd /path/to/project

Change Mode Issues

"Failed to parse changeMode response"

Problem: Structured edits not parsing correctly.

Solution:

// Ensure changeMode is enabled
{
  "prompt": "refactor code",
  "changeMode": true
}

// Handle chunks for large responses
{
  "cacheKey": "response-key",
  "chunkIndex": 1
}

Platform-Specific Issues

macOS

"xcrun: error: invalid active developer path"

Solution:

xcode-select --install

"EACCES: permission denied"

Solution:

# Fix npm permissions
sudo npm install -g @trishchuk/codex-mcp-tool --unsafe-perm

Windows

"EPERM: operation not permitted"

Solutions:

1. Run as Administrator
2. Disable Windows Defender temporarily
3. Use Windows Terminal instead of CMD

Path issues with spaces

Solution:

// Use quotes for paths with spaces
"@\"C:/Program Files/project/src/main.ts\"";

Linux

"ENOSPC: System limit for number of file watchers reached"

Solution:

# Increase file watchers limit
echo fs.inotify.max_user_watches=524288 | sudo tee -a /etc/sysctl.conf
sudo sysctl -p

Debug Mode

Enable detailed logging for troubleshooting:

Environment Variables

# Enable all debug output
DEBUG=* npx @trishchuk/codex-mcp-tool

# Enable specific modules
DEBUG=codex-mcp:* npx @trishchuk/codex-mcp-tool
DEBUG=codex-mcp:executor npx @trishchuk/codex-mcp-tool
DEBUG=codex-mcp:parser npx @trishchuk/codex-mcp-tool

Logging Levels

// In your configuration
{
  "logging": {
    "level": "debug",  // debug, info, warn, error
    "file": "/tmp/codex-mcp.log"
  }
}

Performance Optimization

Slow Response Times

1. Use faster models:

{
  "model": "gpt-5.1-codex-mini"  // Faster than GPT-5
}

2. Optimize file references:

// Be specific about files
'@src/utils/helper.ts'; // Better
'@src/**/*'; // Slower

3. Enable caching:

{
  "cache": true,
  "cacheDir": ".codex-cache"
}

Memory Issues

1. Process files in batches:

// Process directory by directory
'analyze @src/module1/';
'analyze @src/module2/';

2. Clear cache periodically:

rm -rf .codex-cache

Getting Help

Gather Diagnostic Information

When reporting issues, include:

# System information
uname -a
node --version
npm --version
codex --version

# Package information
npm list -g @trishchuk/codex-mcp-tool

# Error logs
cat ~/.codex/logs/error.log

# MCP client version
claude --version  # For Claude Code

Support Channels

1. GitHub Issues: Report bugs
2. Discussions: Ask questions
3. Documentation: Read docs

Creating Bug Reports

Include:

• Clear description of the issue
• Steps to reproduce
• Expected vs actual behavior
• Environment details
• Error messages and logs
• Tool and command used

FAQ

Can I use multiple models in one session?

Yes, specify different models per request:

// First request
{ "prompt": "quick task", "model": "gpt-5.1-codex-mini" }

// Second request
{ "prompt": "complex analysis", "model": "gpt-5.1-codex-max" }

How do I handle large codebases?

1. Use specific file patterns
2. Process in chunks
3. Enable changeMode for structured edits
4. Use progress callbacks

Can I customize timeout settings?

Currently managed internally, but you can:

• Break down large tasks
• Use background processing
• Implement retry logic

Is offline mode supported?

No, Codex CLI requires internet connection to OpenAI API.

Related Resources

• Installation Guide
• API Reference
• Configuration Guide
• Examples