Codex Integration

This guide covers integrating 1MCP with Codex across the three supported paths: CLI mode first, proxy second for maximum compatibility, and direct streamable HTTP third when project context is unnecessary.

CLI Mode First

For Codex sessions, the recommended 1MCP workflow is CLI mode:

• keep your MCP servers behind 1mcp serve
• remove Codex's existing direct MCP server config for this workflow
• bootstrap Codex with 1mcp cli-setup --codex
• let Codex use instructions, inspect, and run progressively

This is the preferred agent-facing path because it reduces unnecessary tool and schema context inside the agent loop without changing the MCP backend that 1MCP is aggregating.

For the conceptual background, see CLI Mode.

Choose only one mode for Codex:

• direct MCP mode
• CLI mode

Do not keep both configured for the same Codex setup. If you choose CLI mode, remove the direct MCP server entry first.

Overview

Codex Version Compatibility

Codex < 0.44.0 (Limited Support)

Codex versions before 0.44.0 have limited MCP server support:

• No HTTP Transport: Cannot connect to HTTP/SSE endpoints directly
• STDIO Only: Only supports STDIO transport for MCP servers
• No Per-Project Settings: Global configuration only, no project-specific server management

Codex ≥ 0.44.0 (HTTP Transport Support)

Codex 0.44.0 and later supports HTTP-based MCP servers natively:

• HTTP Transport: Can connect directly to HTTP/SSE endpoints
• Global Configuration: HTTP servers are configured globally in config.toml
• No Per-Project Settings: Still lacks project-specific server management

Note: Codex per-project configuration is not yet implemented (see pr#4007 on codex).

Why Use 1MCP Proxy Even with Codex ≥ 0.44.0?

While Codex ≥ 0.44.0 can connect directly to HTTP MCP servers, 1MCP proxy is still recommended for several reasons:

1. Per-Project Server Management

# Direct Codex HTTP (Global - affects all projects)
[mcp_servers.1mcp]
url="http://localhost:3050/mcp"

# vs 1MCP Proxy (Per-project via .1mcprc)
# Project A: {"preset": "web-dev"}      # Only web servers
# Project B: {"preset": "data-science"} # Only data servers
# Project C: {"preset": "backend"}     # Only backend servers

2. Advanced Tag-Based Filtering

# 1MCP Proxy: Selective server exposure via presets
npx -y @1mcp/agent preset create web-dev --filter "frontend OR design"
npx -y @1mcp/agent preset create data-science --filter "data-science OR ai"
npx -y @1mcp/agent preset create backend --filter "backend OR api"

3. Centralized Server Management

• Single Source: Manage all MCP servers in one place
• Hot Reloading: Update configurations without restarting Codex
• Team Sharing: Share presets across team members

4. Maximum Client Compatibility

• stdio is widely supported: Most AI clients already support stdio transport
• HTTP support is narrower: Streamable HTTP and SSE support still varies across clients and versions
• One operational pattern: Teams can standardize on serve + proxy + .1mcprc even when clients differ

1MCP Bridge Solution

1MCP provides comprehensive MCP server management through:

• HTTP ↔ STDIO Proxy: Translates between HTTP transport and STDIO transport
• Project-Level Configuration: Per-project MCP server settings via .1mcprc files and presets
• Advanced Filtering: Tag-based server selection and filtering
• Centralized Management: Unified server lifecycle and capability aggregation

The .1mcprc with preset + proxy + serve combination provides different MCP servers for different projects, even with newer Codex versions that support HTTP transport.

Terminology

To avoid confusion, this guide uses the following terms consistently:

Term	Definition	Example Command
1MCP Agent	The overall npm package @1mcp/agent containing all 1MCP functionality	npx -y @1mcp/agent --version
1MCP Server	The HTTP server process started with the serve command that aggregates MCP servers	npx -y @1mcp/agent serve
1MCP Proxy	The STDIO-to-HTTP bridge started with the proxy command for Codex integration	npx -y @1mcp/agent proxy
MCP Server	Individual Model Context Protocol servers (filesystem, github, etc.)	npx @modelcontextprotocol/server-filesystem
Preset	Named configuration defining which MCP servers to expose via tag filtering	npx -y @1mcp/agent preset create my-preset

Architecture Flow:

Codex (STDIO) ← 1MCP Proxy (STDIO↔HTTP) ← 1MCP Server (HTTP) ← MCP Servers

Alternative: Direct HTTP Transport (Codex ≥ 0.44.0)

For simpler setups, connect Codex directly to 1MCP Server via HTTP:

1mcp serve  # Start 1MCP server

Edit config.toml:

[mcp_servers.1mcp]
url = "http://localhost:3051/mcp"

Limitations: All servers available globally (no per-project filtering, no tag-based selection). Use 1MCP Proxy for project-specific server management and team collaboration.

Prerequisites

System Requirements

• Node.js: Version 18+ required for MCP servers and 1MCP agent

  node --version  # Should be v18.0.0 or higher

• 1MCP Agent: Latest version recommended

  # Install globally for easier use (recommended)
  npm install -g @1mcp/agent
  
  # Verify installation
  1mcp --version
  
  # Alternative: Use npx (no installation required)
  npx -y @1mcp/agent --version

Tip: Installing globally with npm install -g @1mcp/agent allows you to use the shorter 1mcp command instead of npx -y @1mcp/agent throughout this guide.

Installation

If you don't have Codex installed, visit the official Codex repository for installation instructions.

Configuration File Locations

Codex stores its configuration in:

• Linux/macOS: ~/.codex/config.toml
• Windows: %APPDATA%\codex\config.toml

Create the directory if it doesn't exist:

mkdir -p ~/.codex  # Linux/macOS

Recommended Bootstrap with cli-setup

If you want Codex sessions to start with the 1MCP bootstrap docs and hooks already wired in, run:

1mcp cli-setup --codex

This writes the managed 1MCP.md bootstrap doc, updates Codex hook configuration, and prints the config.toml snippet required to enable Codex hooks and the correct sandbox settings.

Known Issues

⚠️ Important: Codex 0.44.0's HTTP transport support is experimental. If you experience problems with direct HTTP connections, use the 1MCP proxy method instead. See Troubleshooting for details.

Verification Checklist

Before proceeding, verify:

• [ ] Codex version ≥ 0.44.0 installed (or any version for proxy method)
• [ ] Node.js version ≥ 18 installed
• [ ] Can run 1mcp --version successfully (or npx -y @1mcp/agent --version)
• [ ] Configuration directory exists at ~/.codex/
• [ ] Have a working directory for testing (e.g., ~/test-codex-integration/)

Project Directory

You'll need a workspace directory where you want to use the integration. This is where you'll create the .1mcprc configuration file.

Quick Start

1. Install and Start 1MCP Server

# Add some MCP servers with tags for preset filtering
1mcp mcp add filesystem --tags=files,local -- npx -y @modelcontextprotocol/server-filesystem /tmp
1mcp mcp add github --tags=git,remote,collaboration -- npx -y @modelcontextprotocol/server-github

# Start 1MCP server in background
1mcp serve

Note: If you haven't installed globally, use npx -y @1mcp/agent instead of 1mcp

1.5 Bootstrap Codex for the CLI Workflow

Run this once on the machine where Codex will use 1MCP:

1mcp cli-setup --codex

The installed bootstrap files tell Codex sessions to start with:

1mcp instructions
1mcp inspect <server>
1mcp inspect <server>/<tool>
1mcp run <server>/<tool> --args '<json>'

2. Create Project Configuration

In your Codex project directory, create a .1mcprc file:

{
  "preset": "codex-development"
}

3. Create Preset

# Create a preset for Codex development using tags
1mcp preset create codex-development --filter "files OR git OR collaboration"

Important: Presets filter servers by tags. Always tag your servers or they won't be included in presets.

4. Configure Codex

Add 1MCP proxy as an MCP server in your Codex configuration:

Edit your Codex config.toml file (see Prerequisites for location):

[mcp_servers.1mcp]
command = "npx"
args = ["-y", "@1mcp/agent@latest", "proxy"]

Important:

• The working directory for the 1MCP proxy should be your project directory containing .1mcprc
• Start Codex from your project root to ensure it loads the correct configuration

5. Start Codex in your project directory

cd /path/to/my-project
codex

6. Test in Codex

# Test in Codex
/mcp

7. Use the 1MCP CLI Workflow Inside Codex Sessions

Once Codex is connected, the recommended 1MCP workflow is:

1mcp instructions
1mcp inspect filesystem
1mcp inspect filesystem/read_file
1mcp run filesystem/read_file --args '{"path":"./README.md"}'

Architecture

1MCP Proxy Integration (Recommended)

┌─────────────────┐     STDIO      ┌──────────────────┐      HTTP      ┌─────────────────┐
│      Codex      │ ◄────────────► │    1MCP Proxy    │ ◄────────────► │   1MCP Server   │
│   (any version) │                │   (reads .1mcprc)│                │   (no auth)     │
└─────────────────┘                └──────────────────┘                └─────────────────┘
        │                                   │                                   │
        │                                   │                                   ▼
        │                                   │                          ┌─────────────────┐
        │                                   │                          │   MCP Servers   │
        │                                   │                          │ (filesystem,    │
        ▼                                   ▼                          │  github, db,    │
┌─────────────────┐                ┌──────────────────┐                │  etc.)          │
│ config.toml     │                │ .1mcprc + Preset │                └─────────────────┘
│(MCP server list)│                │ (project config) │                         │
└─────────────────┘                └──────────────────┘                         │
                                                                          Tag-based
                                                                         filtering

Data Flow:

1. Codex Configuration: Add 1MCP proxy as MCP server in config.toml
2. Project Detection: Proxy reads .1mcprc file from current project directory
3. Preset Loading: Proxy loads specified preset configuration
4. Server Connection: Proxy connects to 1MCP server via HTTP
5. Tag Filtering: 1MCP server filters MCP servers based on preset tags
6. Capability Aggregation: Filtered servers are exposed to Codex
7. Bidirectional Communication: MCP protocol flows through the proxy bridge

Direct HTTP Integration (Codex ≥ 0.44.0)

┌─────────────────┐     HTTP/SSE   ┌──────────────────┐
│      Codex      │ ◄────────────► │   1MCP Server    │
│   (≥ 0.44.0)    │                │   (global config)│
└─────────────────┘                └──────────────────┘
        │                                   │
        ▼                                   ▼
┌─────────────────┐                ┌─────────────────┐
│ config.toml     │                │   MCP Servers   │
│ (HTTP URL only) │                │ (all servers,   │
└─────────────────┘                │  no filtering)  │
                                   └─────────────────┘

Limitations: No per-project configuration, no tag filtering, global servers only

Key Differences

Aspect	1MCP Proxy	Direct HTTP
Per-Project Config	✅ .1mcprc files	❌ Global only
Server Filtering	✅ Tag-based presets	❌ All servers
Project Isolation	✅ Different servers per project	❌ Same servers everywhere
Team Sharing	✅ Shareable presets	❌ Manual sync
Setup Complexity	⚠️ Moderate	✅ Simple

Working Directory Requirements

Critical: The 1MCP proxy must be executed from your project directory containing the .1mcprc file:

# ✅ Correct - from project root
cd /path/to/my-project
codex

# ❌ Incorrect - from wrong directory
cd /home/user
codex  # Won't find .1mcprc

If using Codex's configuration file approach, ensure the working directory is set correctly in your MCP server configuration or workspace settings.

Configuration Options

Basic Project Configuration

Create .1mcprc in your project root:

{
  "preset": "development-setup"
}

Advanced Configuration with Filtering

{
  "filter": "web OR api OR filesystem"
}

Multiple Environment Setup

Create different presets for different environments:

Development (.1mcprc.dev):

{
  "preset": "dev-environment",
  "filter": "filesystem,web,database,test"
}

Production (.1mcprc.prod):

{
  "preset": "production",
  "filter": "web,api,database,monitoring"
}

Switch between environments:

# Use development preset
ln -sf .1mcprc.dev .1mcprc

# Use production preset
ln -sf .1mcprc.prod .1mcprc

Preset Management

Creating Presets

# Web development preset
npx -y @1mcp/agent preset create web-dev --filter "filesystem,web,api"

# Data science preset
npx -y @1mcp/agent preset create data-science --filter "filesystem,database,python"

# Full-stack preset
npx -y @1mcp/agent preset create full-stack --filter "web,api,database,filesystem"

Listing Presets

npx -y @1mcp/agent preset list

Using Presets in Projects

Your .1mcprc file simply references the preset:

{
  "preset": "web-dev"
}

This enables:

• Team Consistency: Share presets across team members
• Easy Switching: Change environments by updating preset name
• Centralized Management: Update servers in one place

Example: Project-Specific Presets

# Web development
1mcp mcp add filesystem --tags=files,web -- npx -y @modelcontextprotocol/server-filesystem ./src
1mcp preset create web-dev --filter "files OR git OR web"
echo '{"preset": "web-dev"}' > .1mcprc

# Data science
1mcp mcp add python --tags=python,data -- npx -y @modelcontextprotocol/server-python
1mcp preset create data-science --filter "python OR database OR data"
echo '{"preset": "data-science"}' > .1mcprc

# Team collaboration - different presets per role
1mcp preset create frontend --filter "frontend OR ui OR design"
1mcp preset create backend --filter "backend OR database OR api"

Tags and Presets: Essential Concepts

Why Tags Matter

Tags are the foundation of 1MCP's filtering system. They enable:

1. Project-Specific Servers: Different projects access different MCP servers
2. Team Collaboration: Share presets defining which servers teams need
3. Flexible Grouping: Group servers by functionality, environment, or team
4. Security: Limit access to sensitive servers using tag-based filtering

Key Principle: Presets filter MCP servers based on tags, not server names.

Tag Strategy

Recommended Tag Categories

Category	Examples	Purpose
Functionality	files, database, api, git	What the server does
Environment	development, production, staging	Where it's used
Scope	local, remote, frontend, backend	Access scope
Purpose	tools, monitoring, collaboration	Why it's needed

Adding Tags

Use --tags parameter before -- separator:

1mcp mcp add filesystem --tags=files,local -- npx -y @modelcontextprotocol/server-filesystem ./src

Creating Presets

1mcp preset create dev-tools --filter "development OR tools"
1mcp preset create backend --filter "backend AND development"
1mcp preset create fullstack --filter "(frontend OR backend) AND development"

Common Mistakes

❌ Missing tags: 1mcp mcp add server -- ... ✅ Always tag: 1mcp mcp add server --tags=dev,tools -- ...

❌ Inconsistent: dev, development, dev-mode ✅ Consistent: development everywhere

Debug Commands

1mcp mcp list                    # View all servers and tags
1mcp preset show my-preset       # See which servers preset includes
1mcp proxy --filter "..."        # Test filter expression

Complex Filter Expressions

{
  "filter": "(filesystem AND development) OR (github AND collaboration)"
}

Exclusion Logic

{
  "filter": "web AND NOT test AND NOT debug"
}

Troubleshooting

Server not found: 1mcp mcp status, 1mcp serve (without --enable-auth), test with curl http://localhost:3051/mcp

Config not loading: Check .1mcprc exists (ls -la .1mcprc), validate JSON (cat .1mcprc | jq), test with 1mcp proxy

Preset not found: 1mcp preset list, create it, or use direct filter in .1mcprc

Servers not showing: 1mcp mcp list, verify tags match preset filter, check 1mcp preset show <name>

Codex connection failed:

1. Verify proxy works: 1mcp proxy
2. Check config.toml syntax
3. Confirm server running: curl http://localhost:3051/health
4. Restart Codex

Wrong working directory: Start Codex from project root containing .1mcprc

Tag filtering issues: Verify servers have tags (1mcp mcp list), check preset filter (1mcp preset show <name>)

Preset changes ignored: Restart Codex and 1MCP server (pkill -f "1mcp.*serve" && 1mcp serve)

Debug: 1mcp proxy --log-file=proxy.log, 1mcp mcp status

Performance: Increase timeout with 1mcp proxy --timeout=30000

Best Practices

• Authentication: Proxy doesn't support auth - use 1mcp serve without --enable-auth
• Project Structure: Keep .1mcprc in project root, version control it (unless secrets)
• Tag Consistency: Use standard tag names across team
• Performance: Load only needed servers, use consistent tags for filtering

Next Steps

Create More Presets: 1mcp preset create <name> --filter "<tags>"

Team Onboarding:

• Document setup in project README
• Share .1mcprc and preset configs (version control safe if no secrets)
• Standardize tagging conventions

Optimize:

• Monitor health: 1mcp mcp status
• Pin versions: 1mcp mcp add server --tags=stable -- npx -y @org/server@1.0.0

Related Guides:

• Claude Desktop Integration
• Configuration Guide
• Security Best Practices
• CLI Setup Command
• Instructions Command
• Inspect Command
• Run Command

See Also

• Proxy Command - Detailed proxy command documentation
• Quick Start - Basic 1MCP setup
• Configuration Guide - Advanced configuration options
• Preset Commands - Preset management commands
• MCP Commands - MCP server management
• CLI Setup Command - Install Codex bootstrap docs and hooks
• Instructions Command - Start the CLI workflow with current server guidance
• Inspect Command - Discover tools and inspect schemas before invoking them
• Run Command - Call tools through the running 1MCP instance