Codex Integration

This guide covers integrating 1MCP with Codex to enable advanced MCP server management, per-project configurations, and streamable HTTP transport capabilities.

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

toml

# 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

bash

# 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

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:

bash

1mcp serve  # Start 1MCP server

Edit config.toml:

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
bash
```
node --version  # Should be v18.0.0 or higher
```
1

1MCP Agent: Latest version recommended

bash

# 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:

bash

mkdir -p ~/.codex  # Linux/macOS

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

bash

# 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

2. Create Project Configuration

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

json

{
  "preset": "codex-development"
}

3. Create Preset

bash

# 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):

toml

[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

bash

cd /path/to/my-project
codex

6. Test in Codex

bash

# Test in Codex
/mcp

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:

Codex Configuration: Add 1MCP proxy as MCP server in config.toml
Project Detection: Proxy reads .1mcprc file from current project directory
Preset Loading: Proxy loads specified preset configuration
Server Connection: Proxy connects to 1MCP server via HTTP
Tag Filtering: 1MCP server filters MCP servers based on preset tags
Capability Aggregation: Filtered servers are exposed to Codex
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:

bash

# ✅ 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:

json

{
  "preset": "development-setup"
}

Advanced Configuration with Filtering

json

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

Multiple Environment Setup

Create different presets for different environments:

Development (.1mcprc.dev):

json

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

Production (.1mcprc.prod):

json

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

Switch between environments:

bash

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

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

Preset Management

Creating Presets

bash

# 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

bash

npx -y @1mcp/agent preset list

Using Presets in Projects

Your .1mcprc file simply references the preset:

json

{
  "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

bash

# 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:

Project-Specific Servers: Different projects access different MCP servers
Team Collaboration: Share presets defining which servers teams need
Flexible Grouping: Group servers by functionality, environment, or team
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:

bash

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

Creating Presets

bash

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

bash

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

json

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

Exclusion Logic

json

{
  "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:

Verify proxy works: 1mcp proxy
Check config.toml syntax
Confirm server running: curl http://localhost:3051/health
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/[email protected]

Related Guides:

Codex Integration ​

Overview ​

Codex Version Compatibility ​

Codex < 0.44.0 (Limited Support) ​

Codex ≥ 0.44.0 (HTTP Transport Support) ​

Why Use 1MCP Proxy Even with Codex ≥ 0.44.0? ​

1. Per-Project Server Management ​

2. Advanced Tag-Based Filtering ​

3. Centralized Server Management ​

1MCP Bridge Solution ​

Terminology ​

Alternative: Direct HTTP Transport (Codex ≥ 0.44.0) ​

Prerequisites ​

System Requirements ​

Installation ​

Configuration File Locations ​

Known Issues ​

Verification Checklist ​

Project Directory ​

Quick Start ​

1. Install and Start 1MCP Server ​

2. Create Project Configuration ​

3. Create Preset ​

4. Configure Codex ​

5. Start Codex in your project directory ​

6. Test in Codex ​

Architecture ​

1MCP Proxy Integration (Recommended) ​

Direct HTTP Integration (Codex ≥ 0.44.0) ​

Key Differences ​

Working Directory Requirements ​

Configuration Options ​

Basic Project Configuration ​

Advanced Configuration with Filtering ​

Multiple Environment Setup ​

Preset Management ​

Creating Presets ​

Listing Presets ​

Using Presets in Projects ​

Example: Project-Specific Presets ​

Tags and Presets: Essential Concepts ​

Why Tags Matter ​

Tag Strategy ​

Recommended Tag Categories ​

Adding Tags ​

Creating Presets ​

Common Mistakes ​

Debug Commands ​

Complex Filter Expressions ​

Exclusion Logic ​

Troubleshooting ​

Best Practices ​

Next Steps ​

See Also ​

Codex Integration

Overview

Codex Version Compatibility

Codex < 0.44.0 (Limited Support)

Codex ≥ 0.44.0 (HTTP Transport Support)

Why Use 1MCP Proxy Even with Codex ≥ 0.44.0?

1. Per-Project Server Management

2. Advanced Tag-Based Filtering

3. Centralized Server Management

1MCP Bridge Solution

Terminology

Alternative: Direct HTTP Transport (Codex ≥ 0.44.0)

Prerequisites

System Requirements

Installation

Configuration File Locations

Known Issues

Verification Checklist

Project Directory

Quick Start

1. Install and Start 1MCP Server

2. Create Project Configuration

3. Create Preset

4. Configure Codex

5. Start Codex in your project directory

6. Test in Codex

Architecture

1MCP Proxy Integration (Recommended)

Direct HTTP Integration (Codex ≥ 0.44.0)

Key Differences

Working Directory Requirements

Configuration Options

Basic Project Configuration

Advanced Configuration with Filtering

Multiple Environment Setup

Preset Management

Creating Presets

Listing Presets

Using Presets in Projects

Example: Project-Specific Presets

Tags and Presets: Essential Concepts

Why Tags Matter

Tag Strategy

Recommended Tag Categories

Adding Tags

Creating Presets

Common Mistakes

Debug Commands

Complex Filter Expressions

Exclusion Logic

Troubleshooting

Best Practices

Next Steps

See Also