Codex integration

Install and wire mog skills, rules, and MCP servers into OpenAI Codex with automatic configuration.

mog has first-class support for OpenAI Codex. The CLI auto-detects Codex projects, installs packages to the right paths, and writes MCP server config directly to .codex/config.toml.

How auto-detection works

When you run mog install in a project directory, the CLI looks for a .codex/ directory. If it finds one, it sets the target to codex and uses Codex-specific install paths. You can always override with --target codex.

Installing skills

Skills are SKILL.md packages that teach Codex specific capabilities.

mog install acme/react-testing-skill

This downloads the package, verifies its SHA-256 hash, and extracts it to:

mog_modules/react-testing-skill/
  SKILL.md
  README.md

Codex reads skills from .agents/skills/ directories at multiple scopes (repository, user, admin). After installing with mog, you can symlink or copy the skill into Codex's expected location:

mkdir -p .agents/skills
ln -s ../../mog_modules/react-testing-skill .agents/skills/react-testing-skill

Codex discovers the SKILL.md inside the directory and makes the skill available to the agent.

Global skills

Codex also loads skills from $HOME/.agents/skills/ (user scope). To install a skill for use across all your repositories:

mog install acme/react-testing-skill --target codex
cp -r mog_modules/react-testing-skill ~/.agents/skills/react-testing-skill

Installing MCP servers

MCP server packages are installed by writing configuration to .codex/config.toml — no file extraction needed.

mog install acme/github-mcp-server

The CLI prompts for any required environment variables and writes the config:

[mcp_servers.acme-github-mcp-server]
command = "npx"
args = ["-y", "@acme/github-mcp-server@1.0.0"]
 
[mcp_servers.acme-github-mcp-server.env]
GITHUB_TOKEN = "ghp_your_token"

If .codex/config.toml already has other servers or settings configured, mog merges the new entry without overwriting existing ones.

Passing env vars non-interactively

For CI or agent-driven installs, pass environment variables with --env:

mog install acme/github-mcp-server --env GITHUB_TOKEN=ghp_xxx

HTTP transport

For remotely-hosted MCP servers, Codex supports HTTP transport:

[mcp_servers.acme-remote-server]
url = "https://mcp.acme.dev/sse"
bearer_token_env_var = "ACME_API_KEY"

Project health check

Run mog doctor to verify your Codex project is set up correctly:

mog doctor

This checks:

CLI authentication status
Lockfile integrity (mog.lock.json)
Installed packages match the lockfile (version and SHA-256)
MCP server config validity in .codex/config.toml

Listing installed packages

mog ls

2 installed packages

acme/react-testing-skill@1.2.0  codex
  mog_modules/react-testing-skill/
  Installed: 1/15/2026

acme/github-mcp-server@1.0.0  codex (mcp)
  .codex/config.toml
  Installed: 1/16/2026

Updating packages

mog update --dry-run
mog update

Updates respect semver: by default only patch and minor versions are applied. The lockfile is updated and the old files are replaced.

Uninstalling

mog uninstall acme/react-testing-skill

For skills, this removes the extracted files from mog_modules/ and the lockfile entry. You'll need to remove any symlinks in .agents/skills/ manually.

For MCP servers, this removes the mcp_servers entry from .codex/config.toml.

File layout summary

After installing a mix of skills and MCP servers, your Codex project looks like this:

my-project/
  .codex/
    config.toml                        # MCP server configs (auto-managed)
  .agents/
    skills/
      react-testing-skill -> ../../mog_modules/react-testing-skill
  mog_modules/
    react-testing-skill/
      SKILL.md
      README.md
  mog.lock.json                        # Lockfile (commit to version control)

Tips

Commit mog.lock.json to version control so teammates get the same package versions.
Don't commit secrets in .codex/config.toml — use environment variable references instead of hardcoded API keys.
Codex supports profiles in config.toml for switching between named configurations. You can have different MCP server sets for different workflows.
Use mog explain <vendor>/<package> to preview a package's metadata, install path, and target compatibility before installing.
Use mog install --preflight to see exactly what would happen without making changes.