// 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 agent-root install fstools.dev/fs-mcp --tool codex
# Adds to Codex MCP configuration:
# ~/.codex/config.json
{
"mcpServers": {
"fs-mcp": {
"command": "npx",
"args": ["@fstools/fs-mcp"]
}
}
}
Installing skills:
$ npx agent-root install pycraft.io/python-patterns --tool codex
# Downloads skill files to:
# ~/.codex/skills/pycraft.io/python-patterns/async-patterns.md
# ~/.codex/skills/pycraft.io/python-patterns/testing-guide.md
# ~/.codex/skills/pycraft.io/python-patterns/packaging.md
After installing an MCP server, you must restart Codex CLI for the new server to be available. Codex loads 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 agent-root install pycraft.io/python-patterns --tool codex
# Installs to: ~/.codex/skills/
# Project-scoped — only available in this project
$ npx agent-root install pycraft.io/python-patterns --tool codex --scope 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: Restart Codex CLI after installing. Check
~/.codex/config.json for the server entry.
- Skills not loading: Verify files exist at
~/.codex/skills/ or .agents/skills/. Confirm trigger keywords in the skill frontmatter match your queries.
- Command not found: Ensure the MCP server's npm package is installed globally or available via
npx.
- Outdated records: Re-run the install command to pull the latest version.
// next_steps