Navigate
// install_codex
Using AgentRoot with Codex CLI
Search the AgentRoot registry and install MCP servers and skills into Codex CLI. Skills are placed in Codex's skill directories, and MCP servers are added to your Codex configuration.
// what_you_need
- Codex CLI installed (
npm i -g @openai/codex) - Node.js 18+
- A project directory (for project-scoped installs)
1Search the registry
# Search for MCP servers
$ npx agent-root search "file management" --type mcp
fstools.dev/fs-mcp mcp Filesystem MCP Server
transport: stdio | tools: read, write, search, tree
# Search for skills
$ npx agent-root search "python" --type skill
pycraft.io/python-patterns skill Python Best Practices
skills: async-patterns, testing-guide, packaging
2Install a record
Use the --tool codex flag to install into Codex CLI:
Installing an MCP server:
$ npx -p @agent-root/cli agent-root install fstools.dev/fs-mcp --tool codex
# The CLI prints the JSON snippet to add to your Codex config:
{
"mcpServers": {
"fs-mcp": {
"command": "npx",
"args": ["@fstools/fs-mcp"]
}
}
}
Install never mutates Codex's config file automatically. Paste the snippet into the file Codex reads on startup, then restart Codex.
Installing skills:
$ npx -p @agent-root/cli agent-root install pycraft.io/python-patterns --tool codex
# Writes skill files into Codex's global skills dir:
# ~/.codex/skills/pycraft.io/python-patterns/SKILL.md
# (plus any referenced supporting files)
After pasting MCP config into Codex, restart Codex CLI for the new server to load. Codex reads MCP configuration at startup.
3Verify it works
Restart Codex and confirm the MCP tools are loaded:
$ codex
# In the Codex session, the MCP tools should be available
# Try: "List files in the current directory using the fs-mcp tools"
For skills, Codex loads them as context when your prompts match trigger keywords.
4Project-scoped vs global installs
# Global install (default) — available in all Codex sessions
$ npx -p @agent-root/cli agent-root install pycraft.io/python-patterns --tool codex
# Installs to: ~/.codex/skills/
# Project-scoped — only available in this project
$ npx -p @agent-root/cli agent-root install pycraft.io/python-patterns --tool codex --project
# Installs to: .agents/skills/
Project-scoped skills use the .agents/skills/ directory convention. This directory is shared across tools that support the .agents/ standard, so skills installed here also work with Gemini CLI.
// troubleshooting
- MCP server not available: The CLI prints the config block but does not write it. Paste it into the file Codex reads at startup, then restart Codex CLI.
- Skills not loading: Verify files exist at
~/.codex/skills/<domain>/<record-id>/(global) or.agents/skills/<domain>/<record-id>/(project). Confirm trigger keywords in the SKILL.md frontmatter match your queries. - Command not found: Ensure the MCP server's npm package is installed globally or available via
npx. - Outdated records: Run
agent-root update <domain>/<record-id>to re-fetch from the publisher.