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, 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 # provides `uvx`; if missing: curl -LsSf https://astral.sh/uv/install.sh | sh
codex --version # OpenAI Codex CLI; if missing: https://developers.openai.com/codex
Install (two commands)
# 1. Register the ToolUniverse marketplace from GitHub
codex plugin marketplace add mims-harvard/ToolUniverse
# 2. Install the plugin from that marketplace
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 # expect: tooluniverse (enabled)
codex plugin list --json # the JSON includes the installed "version"
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"# ...then start codex from that same shell
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 # all configured Git marketplaces
codex plugin marketplace upgrade tooluniverse # just this one
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:
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 tooluniverseshadowsuvx. Fix: uv tool uninstall tooluniverse, then restart.
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.
# 1. Is uv/uvx installed? (most common cause of "no tools at all")command -v uvx || echo"FIX: curl -LsSf https://astral.sh/uv/install.sh | sh"# 2. Can the MCP package resolve + run? (non-hanging proxy for the server)
uvx --from tooluniverse tu --version || echo"FIX: uv/Python issue — see steps 1 and 6"# 3. Is the plugin installed + enabled?
codex plugin list | grep -q tooluniverse || echo"FIX: codex plugin add tooluniverse -m tooluniverse"# 4. Running an OLD version even after updating? (a global install shadows uvx)
uv tool list | grep -q tooluniverse \
&& echo"FIX: uv tool uninstall tooluniverse" \
|| echo"ok: nothing shadowing uvx"# 5. Pull the latest plugin version now (don't wait for next startup)
codex plugin marketplace upgrade tooluniverse
# 6. Python too old (requires >= 3.10)?
uv python install 3.12
# 7. Force a fresh tool package
uv cache clean tooluniverse # or one-shot: uvx --refresh tooluniverse --version
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.
