Jeff31UK/codex-persistent-remote-mcp

Codex Persistent Remote MCP Server

A secure, network-accessible MCP (Model Context Protocol) server that provides persistent Codex (GPT-5) sessions via HTTP. No Codex API key needed - just an OpenAI flat-rate subscription with Codex access. This server allows you to run Codex AI sessions that can be accessed from multiple computers on your network, with built-in security features and session management.

Why This Exists

This server bridges Codex (OpenAI's GPT-5 model) with Claude Code through the MCP protocol, enabling:

• No API Key Costs: Uses your OpenAI flat-rate subscription, not usage-based billing
• Persistent Sessions: Keep Codex conversations alive across multiple interactions
• Network Access: Access your Codex instance from any computer on your network
• Multiple Sessions: Run multiple independent Codex sessions simultaneously
• Security: Built-in authentication, rate limiting, and IP restrictions
• Session Management: Automatic cleanup of inactive sessions

Quick Start

1. Install

git clone https://github.com/Jeff31UK/codex-persistent-remote-mcp.git
cd codex-persistent-remote-mcp
npm install

2. Generate Server API Key (REQUIRED for network access)

openssl rand -hex 32
# Copy this key for securing your MCP server (not for Codex/OpenAI)

3. Start Server

# Run with API key (required for security)
MCP_API_KEY=your-generated-key AUTO_EXIT=false npm start

4. Connect from Claude Code

# Add the MCP server to Claude Code
claude mcp add --transport http codex-persistent http://YOUR-IP:3000/mcp \
  --header "Authorization: Bearer your-generated-key"

# Find your server IP with:
ip addr show  # Linux/Mac
ipconfig      # Windows

5. Use in Claude Code

Once connected, you'll have access to these tools in Claude Code:

• start_session - Start a new Codex session
• send_prompt - Send prompts to Codex
• end_session - Close a session
• list_sessions - View active sessions

Features

🔒 Security Features

• API Key Authentication: Bearer token authentication for all MCP endpoints
• Rate Limiting: 100 requests/minute per IP (prevents abuse)
• IP Allowlisting: Optional IP restriction (defaults to allowing all)
• CORS Protection: Validates origin headers
• Network Binding Control: Choose localhost-only or network-wide access

🚀 Session Management

• Persistent Sessions: Sessions stay alive between requests
• Multiple Sessions: Run many independent Codex instances
• Auto-cleanup: Inactive sessions cleaned up after 30 minutes
• No Auto-exit Option: Server can run indefinitely with AUTO_EXIT=false

🎯 Codex Configuration

• Model Selection: Choose GPT-5 reasoning levels (minimal, low, medium, high)
• Approval Policies: Configure command approval (untrusted, on-failure, on-request, never)
• Sandbox Modes: Control file system access levels

Configuration Options

Environment Variables

Create a .env file (see .env.example):

# Server Configuration
PORT=3000                    # Server port (default: 3000)
HOST=0.0.0.0                 # Bind address (0.0.0.0 for network, 127.0.0.1 for localhost)
AUTO_EXIT=false              # Keep running when no sessions (default: true)

# Security (REQUIRED for network access!)
MCP_API_KEY=your-key-here    # API key for authentication
ALLOWED_IPS=                 # Comma-separated IP list (empty = allow all)

Codex Session Options

When starting a session, you can configure:

{
  "model": "gpt-5-medium",        // Reasoning effort level
  "approval_policy": "never",      // Command approval policy  
  "sandbox": "read-only",          // File system access level
  "config_options": {              // Additional options
    "model_reasoning_effort": "high"
  }
}

Model Options:

• gpt-5-minimal: Fastest responses, limited reasoning
• gpt-5-low: Balance of speed and reasoning
• gpt-5-medium: Default, solid balance (recommended)
• gpt-5-high: Maximum reasoning for complex problems

Sandbox Options:

• none: Full file system access (danger!)
• read-only: Read files only
• workspace-write: Read all, write to workspace
• danger-full-access: Full access (use with caution)

Security Best Practices

For Local Network Use

# Minimum security setup
MCP_API_KEY=$(openssl rand -hex 32)
AUTO_EXIT=false
npm start

For Production/Internet Exposure

1. Always use HTTPS with a reverse proxy:

# nginx.conf
server {
    listen 443 ssl;
    server_name your-domain.com;
    
    ssl_certificate /path/to/cert.pem;
    ssl_certificate_key /path/to/key.pem;
    
    location /mcp {
        proxy_pass http://127.0.0.1:3000;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection 'upgrade';
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_cache_bypass $http_upgrade;
    }
}

2. Restrict IPs when possible:

ALLOWED_IPS=192.168.1.100,192.168.1.101 npm start

3. Use strong API keys and rotate them regularly
4. Monitor logs for suspicious activity
5. Keep the server updated

Deployment Options

System Service (Linux)

Create /etc/systemd/system/codex-mcp.service:

[Unit]
Description=Codex Persistent MCP Server
After=network.target

[Service]
Type=simple
User=youruser
WorkingDirectory=/path/to/codex-persistent-remote-mcp
ExecStart=/usr/bin/npm start
Restart=always
Environment="MCP_API_KEY=your-key"
Environment="AUTO_EXIT=false"

[Install]
WantedBy=multi-user.target

Enable and start:

sudo systemctl enable codex-mcp
sudo systemctl start codex-mcp

Docker (Coming Soon)

Docker support is planned for easier deployment and isolation.

API Endpoints

• POST /mcp - MCP protocol endpoint (requires authentication)
• GET /health - Health check endpoint (no auth required)

Troubleshooting

Server won't start

• Check if port 3000 is already in use: lsof -i :3000
• Verify Node.js version: node --version (requires v18+)

Can't connect from Claude Code

• Verify server is running: curl http://localhost:3000/health
• Check firewall settings allow port 3000
• Ensure API key is correctly set in both server and client

Sessions timeout quickly

• Increase session timeout in code if needed
• Ensure AUTO_EXIT=false is set
• Check server logs for errors

Authentication errors

• Verify API key matches exactly (no extra spaces)
• Check Authorization header format: Bearer your-key
• Ensure MCP_API_KEY environment variable is set

Development

Run in Development Mode

npm run dev  # Watches for file changes

Project Structure

├── src/
│   ├── index.js          # Entry point
│   ├── server.js         # HTTP server & MCP setup
│   └── sessionManager.js # Codex session management
├── .env.example          # Environment template
├── .gitignore           # Git ignore rules
├── package.json         # Dependencies
└── README.md           # This file

Requirements

• Node.js v18 or higher
• Codex CLI installed and configured
• OpenAI flat-rate subscription with Codex access (no API key needed)
• Network access (for remote connections)

License

MIT License - See LICENSE file for details

Contributing

Contributions are welcome! Please:

1. Fork the repository
2. Create a feature branch
3. Commit your changes
4. Push to the branch
5. Open a Pull Request

Security Disclosure

Found a security issue? Please email security@yourproject.com instead of using the issue tracker.

Acknowledgments

• Built on the Model Context Protocol (MCP)
• Integrates with OpenAI's Codex (GPT-5) using flat-rate subscription
• Designed for use with Claude Code
• No Codex API keys or usage-based billing required

Support

• Issues: GitHub Issues
• Discussions: GitHub Discussions

⚠️ Important: Never expose this server to the internet without proper authentication and HTTPS!