| name | tooluniverse-codex-plugin |
| description | Install, set up, verify, update, pin, uninstall, or troubleshoot the ToolUniverse plugin on OpenAI Codex. ALWAYS consult this skill for any of those — don't answer from memory, because the exact marketplace name (mims-harvard/ToolUniverse), the "codex plugin marketplace add" then "codex plugin add -m tooluniverse" flow, Codex's startup auto-upgrade behavior, the uvx tooluniverse MCP server, and the API-key env vars are easy to get wrong. Use it whenever someone wants to get ToolUniverse (or "the 1000+ scientific tools" / "the harvard tools") working on Codex, says the Codex plugin or its tools/skills won't load, hits a uvx or MCP-server startup error, asks how Codex updates it, wants to pin or remove it, or finds it running an old tool version — even if they never say the word "plugin". Not for the Claude Code plugin (use tooluniverse-claude-code-plugin), for running research with the tools, or for authoring new tools or skills. |
Install the ToolUniverse Plugin for OpenAI Codex
One-step install on Codex: an MCP server exposing 1000+ scientific tools plus 130+ research skills — all auto-configured. (For the Claude Code version, see tooluniverse-claude-code-plugin.)
Prerequisites (check once)
uv --version
codex --version
Install (two commands)
codex plugin marketplace add mims-harvard/ToolUniverse
codex plugin add tooluniverse -m tooluniverse
Restart Codex. The MCP server auto-starts via uvx tooluniverse on first use (~30 s cold start while the package downloads, instant after).
mims-harvard/ToolUniverse is an owner/repo shorthand, so Codex records it as a Git marketplace — which is what enables automatic updates (see "Updates"). Don't point it at the plugin subfolder or a raw URL.
Verify it worked
codex plugin list
codex plugin list --json
Then just ask naturally inside Codex:
What are the top mutated genes in breast cancer?
Research the drug metformin.
The research skills auto-activate on matching questions, and the MCP tools are discovered and run via find_tools → execute_tool — no command prefix needed.
What you get
| Component | What it does | How it's used |
|---|
| MCP server | 1000+ tools via find_tools, get_tool_info, execute_tool | Auto-loaded; no action needed |
| 130+ skills | Structured research workflows — drug discovery, variant interpretation, pharmacovigilance, phylogenetics, statistical modeling, and more | Auto-activate on matching questions |
Unlike the Claude Code plugin, the Codex plugin ships MCP tools + skills only — there are no slash commands. You drive everything by asking naturally.
API keys (optional, but recommended)
Most tools work without keys. For higher rate limits or gated databases, set the keys you care about in the environment you launch Codex from — the MCP server (uvx tooluniverse) inherits them:
export NCBI_API_KEY="your_key"
export ONCOKB_API_TOKEN="your_token"
export SEMANTIC_SCHOLAR_API_KEY="your_key"
Exported env vars are the durable choice because they survive plugin upgrades. (You can instead edit the env block of the installed plugin's .mcp.json in the cache — see below — but the cached copy is replaced on every update.)
Full key list: the bundled setup-tooluniverse skill → API_KEYS_REFERENCE.md.
Updates
Codex auto-upgrades Git marketplaces on startup by default. Because you added mims-harvard/ToolUniverse (owner/repo) as a Git marketplace, a newly published version reaches you on your next Codex launch with no action needed. (There is no codex plugin update command — updating is marketplace-driven.)
Refresh on demand instead of waiting:
codex plugin marketplace upgrade
codex plugin marketplace upgrade tooluniverse
In the TUI, open /plugins and press Ctrl+U on the marketplace tab.
The tools themselves come from the tooluniverse PyPI package via uvx, so if tools feel stale after an upgrade, clear the uvx cache:
uv cache clean tooluniverse
Pin the tool version (optional, for reproducibility)
To lock tool behavior for a long-running analysis, edit the installed plugin's .mcp.json and pin the package version:
"args": ["tooluniverse@1.3.0"]
Replace 1.3.0 with any release from https://pypi.org/project/tooluniverse/, then restart Codex. (Find the file under ~/.codex/plugins/cache/.)
Uninstall
codex plugin remove tooluniverse
codex plugin marketplace remove tooluniverse
Alternative install (local checkout / air-gapped)
git clone https://github.com/mims-harvard/ToolUniverse.git
codex plugin marketplace add ./ToolUniverse
codex plugin add tooluniverse -m tooluniverse
A marketplace added by local path is NOT auto-upgraded (only owner/repo Git marketplaces are). After pulling new commits, re-run codex plugin marketplace upgrade or restart Codex.
Troubleshooting
| Symptom | Fix |
|---|
marketplace add fails | Use mims-harvard/ToolUniverse (owner/repo), not a path to the plugin subfolder or a raw URL. |
uvx: command not found | Install uv (see Prerequisites), reopen the terminal. |
| Plugin installed but no tools | Restart Codex; the first launch downloads the package (~30 s). Sanity-check the server: run uvx tooluniverse in a terminal. |
| MCP server won't start | If uvx tooluniverse also fails in a plain terminal, it's a uv/Python issue, not Codex. |
requires-python >= 3.10 | uv python install 3.12 |
| Tools feel outdated after update | uv cache clean tooluniverse, then restart Codex. |
| Update never arrived | Auto-upgrade only applies to Git marketplaces (owner/repo). If you added a local path, run codex plugin marketplace upgrade. |
| Tools run an OLD version | uv tool list | grep tooluniverse — a global uv tool install tooluniverse shadows uvx. Fix: uv tool uninstall tooluniverse, then restart. |
Still stuck: https://github.com/mims-harvard/ToolUniverse/issues
Automated diagnosis & repair
Hand this skill to the agent — "read the tooluniverse-codex-plugin skill and diagnose & fix my Codex plugin" — or run these in order. Each is safe and idempotent; apply the FIX for whatever fails, then restart Codex.
command -v uvx || echo "FIX: curl -LsSf https://astral.sh/uv/install.sh | sh"
uvx --from tooluniverse tu --version || echo "FIX: uv/Python issue — see steps 1 and 6"
codex plugin list | grep -q tooluniverse || echo "FIX: codex plugin add tooluniverse -m tooluniverse"
uv tool list | grep -q tooluniverse \
&& echo "FIX: uv tool uninstall tooluniverse" \
|| echo "ok: nothing shadowing uvx"
codex plugin marketplace upgrade tooluniverse
uv python install 3.12
uv cache clean tooluniverse
For plugin maintainers
This skill documents the user-facing install flow. The Codex plugin source lives at plugins/tooluniverse/ with its own .codex-plugin/plugin.json, .mcp.json, and skills/. The repo-root .agents/plugins/marketplace.json is what makes codex plugin marketplace add mims-harvard/ToolUniverse work — it lists the plugin with "source": {"source": "local", "path": "./plugins/tooluniverse"} (a path inside the cloned marketplace repo, not an external one).
- Skills are generated copies — edit the canonical
skills/ tree, then run plugin/sync-skills.sh. It rebuilds both the Claude and Codex skill sets and applies the Codex-specific normalizations (drops the disable-model-invocation marker Codex ignores, compacts descriptions over Codex's 1024-char limit).
- The Codex plugin version lives in
plugins/tooluniverse/.codex-plugin/plugin.json; scripts/release-plugin.sh bumps it alongside the Claude manifests so both plugins stay on <package MAJOR.MINOR>.<plugin revision>.
- Codex delivers updates via the git push (startup auto-upgrade), independent of the version string — but the bump keeps the two plugins coherent and serves Codex's per-version cache.
