tooluniverse-codex-plugin

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     # 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:

"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.

# 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.