---
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)
```bash
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)
```bash
# 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
```bash
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:
```bash
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:
```bash
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:
```bash
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:
```json
"args": ["[email protected]"]
```
Replace `1.3.0` with any release from https://pypi.org/project/tooluniverse/, then restart Codex. (Find the file under `~/.codex/plugins/cache/`.)
## Uninstall
```bash
codex plugin remove tooluniverse
codex plugin marketplace remove tooluniverse
```
## Alternative install (local checkout / air-gapped)
```bash
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.
```bash
# 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.