Setup ToolUniverse

Guide the user step-by-step through setting up ToolUniverse with MCP (Model Context Protocol) integration.

Agent Behavior — READ THIS FIRST AND ENFORCE IT THROUGHOUT

This is a setup wizard, not a reference manual. You must stay interactive at every step.

The one rule that overrides everything else

After every single step: STOP. Ask if it worked. Wait for the user's reply before continuing. Never run ahead. Never explain Step 3 while the user is still on Step 1. Never output a wall of instructions. One step, then pause.

How to behave at each step

• Show one thing at a time. Give one command or one question. Wait for the result.
• Confirm before moving on. "Did that work? What did you see?" — then react to the answer.
• Explain briefly what each step does and why, in plain language. One sentence is enough.
• Use the AskQuestion tool for structured choices when available (client selection, research areas, etc.).
• Detect the user's language from their first message. If they write in Chinese, Japanese, Spanish, etc., respond in that language throughout the entire setup. All explanations, questions, and celebrations should be in their language. Only keep commands, code blocks, URLs, and env variable names in English (those are technical and must stay as-is).
• Celebrate small wins — when uv installs successfully, when the MCP server appears, when the first tool call works.
• When something goes wrong, be reassuring and help troubleshoot before moving on.

What NOT to do

• ❌ Do not paste multiple steps at once
• ❌ Do not pre-explain upcoming steps "just in case"
• ❌ Do not move to the next step without hearing that the current one succeeded
• ❌ Do not reproduce large blocks from the reference files — summarize and act

Internal Notes (do not show to user)

⚠️ ToolUniverse has 1000+ tools which will cause context window overflow if all exposed directly. The default

tooluniverse

This skill's own URL (for bootstrapping):

https://raw.githubusercontent.com/mims-harvard/ToolUniverse/main/skills/setup-tooluniverse/SKILL.md

Reference files — fetch by GitHub raw URL (works whether this skill was loaded locally or from GitHub):

CLAUDE_DESKTOP.md

API_KEYS_REFERENCE.md

MCP_CONFIG.md

SKILLS_CATALOG.md

TROUBLESHOOTING.md

GITHUB_ISSUE.md

TRAE.md

Step 0: Auto-Detect & Quick Start

Self-declaration first — do this before any detection: You already know what client you are. Open by stating your identity and asking:

"I'm setting this up in [Client Name, e.g. Cursor / Trae / Claude Desktop]. Are you installing ToolUniverse for me to use here, or for a different app?"

• "For you / this app" (most common): Skip the detection commands below. You already know your own config path and OS. Go directly to the correct row in the config table in Step 2.
• "For a different app" or "Not sure": Run the detection commands below to identify the target client and OS.

Detection commands (only run if setting up for a different app or user is unsure):

echo "=== Detecting OS ===" && \
  ([ "$(uname)" = "Darwin" ] && echo "OS: macOS") || \
  ([ "$(uname)" = "Linux" ] && echo "OS: Linux") || \
  echo "OS: Unknown"

echo "=== Detecting your AI client ===" && \
  ([ -f ~/.cursor/mcp.json ] && echo "✅ Cursor detected") || true && \
  ([ -f ~/Library/Application\ Support/Claude/claude_desktop_config.json ] && echo "✅ Claude Desktop detected (macOS)") || true && \
  ([ -f ~/.config/Claude/claude_desktop_config.json ] && echo "✅ Claude Desktop detected (Linux)") || true && \
  ([ -f ~/.claude.json ] && echo "✅ Claude Code detected") || true && \
  ([ -f ~/.codeium/windsurf/mcp_config.json ] && echo "✅ Windsurf detected") || true && \
  ([ -f ~/.gemini/settings.json ] && echo "✅ Gemini CLI detected") || true && \
  ([ -f ~/.gemini/antigravity/mcp_config.json ] && echo "✅ Antigravity detected") || true && \
  ([ -d ~/Library/Application\ Support/Trae ] && echo "✅ Trae detected (macOS)") || true && \
  ([ -d ~/.config/Trae ] && echo "✅ Trae detected (Linux)") || true && \
  ([ -f ~/.codex/config.toml ] && echo "✅ Codex CLI detected") || true && \
  ([ -f ~/.qwen/settings.json ] && echo "✅ Qwen Code detected") || true && \
  ([ -f opencode.json ] && echo "✅ OpenCode detected") || true && \
  echo "=== Detection complete ==="

On Windows, the bash script won't run. Use this PowerShell block instead:

@(
  "$env:USERPROFILE\.cursor\mcp.json",
  "$env:APPDATA\Claude\claude_desktop_config.json",
  "$env:USERPROFILE\.codeium\windsurf\mcp_config.json",
  "$env:USERPROFILE\.gemini\settings.json",
  "$env:USERPROFILE\.gemini\antigravity\mcp_config.json",
  "$env:USERPROFILE\.qwen\settings.json",
  "$env:APPDATA\Trae"
) | ForEach-Object { if (Test-Path $_) { "✅ Detected: $_" } }

Remember the detected OS — it changes config paths, uv install commands, and log locations in later steps.

Based on results:

• One client detected: "I can see you're using [Client]. I'll set up ToolUniverse for that." Skip Question 1.
• Multiple detected: Ask which one to configure.
• None detected: Ask Question 1 below.

⏸️ Now: Report what was detected, then ask Question 1 if needed. Wait for the client answer before continuing.

Question 1 (only if not auto-detected): Which app are you using? Cursor · Claude Desktop · VS Code / Copilot · Windsurf · Claude Code · Gemini CLI · Qwen Code · Codex (OpenAI) · Cline · Trae · Antigravity · OpenCode · Other

⚠️ If Claude Desktop is detected or selected: Step 2 is completely different — you must fetch and follow CLAUDE_DESKTOP.md instead of the standard config. Hold this in mind.

⚠️ If Trae is detected or selected: Step 2 is different — fetch and follow TRAE.md instead of the standard config. URL:

https://raw.githubusercontent.com/mims-harvard/ToolUniverse/main/skills/setup-tooluniverse/TRAE.md

Bootstrap check (terminal-based clients only — OpenCode, Gemini CLI, Codex CLI, Claude Code): If the user arrived here from README/docs (not from inside their client), give them this one-liner to paste into their client instead and stop:

Please read https://raw.githubusercontent.com/mims-harvard/ToolUniverse/main/skills/setup-tooluniverse/SKILL.md and follow it to help me set up ToolUniverse.

⏸️ Now: Ask "Would you like a quick start (~3 min, no questions) or a full setup (API keys + options)?" — then wait for the answer.

• Quick start:

  brew install uv

  (or curl), write config with python3 one-liner, restart app, confirm tools appear, install skills with

  npx skills add mims-harvard/ToolUniverse --all

  . Skip API keys (add later). Skills are included — they're what make ToolUniverse genuinely useful.
• Full setup: Continue with all steps including API keys.

Question 2 (full setup only): How will you use ToolUniverse?

• MCP server (use scientific tools through chat) — default for most users
• Python coding (write scripts that

  import tooluniverse

  ) — also needs pip install

⏸️ Wait for Question 2 answer before proceeding to Step 1.

Step 1: Make sure uv is installed

Check first — skip install entirely if uv is already present:

which uv && uv --version || echo "NOT_INSTALLED"

Windows PowerShell equivalent:

if (Get-Command uv -ErrorAction SilentlyContinue) { uv --version } else { Write-Output 'NOT_INSTALLED' }

• Found: "✅ uv is already installed — skipping." Go to Step 2.
• NOT_INSTALLED: Explain uv is a fast package manager that makes MCP setup simple, then install.

macOS — check for Homebrew first (preferred for Claude Desktop):

which brew && echo "Homebrew found" || echo "No Homebrew"

• Homebrew found:

  brew install uv
  

  Verify with Homebrew path directly (GUI apps use this, not the shell's

  which uvx

  ):

  /opt/homebrew/bin/uvx --version   # Apple Silicon
  /usr/local/bin/uvx --version      # Intel Mac
  

• No Homebrew:

  curl -LsSf https://astral.sh/uv/install.sh | sh
  source "$HOME/.local/bin/env" 2>/dev/null || source ~/.zshrc 2>/dev/null || source ~/.bashrc 2>/dev/null
  

Linux:

curl -LsSf https://astral.sh/uv/install.sh | sh && source "$HOME/.local/bin/env" 2>/dev/null || source ~/.bashrc

Windows (PowerShell):

powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

Verify:

uvx --version

⏸️ After Step 1: Ask "Did

uvx --version

print a version number?" Wait for confirmation before continuing.

Step 2: Add ToolUniverse to your MCP config

🖥️ Claude Desktop users — your path diverges here

Fetch and read this file now, then follow it entirely for Step 2: https://raw.githubusercontent.com/mims-harvard/ToolUniverse/main/skills/setup-tooluniverse/CLAUDE_DESKTOP.md

CLAUDE_DESKTOP.md contains all Claude Desktop-specific instructions: the PATH fix (Claude Desktop is a GUI app that cannot see

uvx

All other clients — standard config

First, validate uvx tooluniverse works before touching any config:

uvx tooluniverse --help

• Prints usage text → proceed.
• Error → fix the uv install (see TROUBLESHOOTING.md Issue 2) before writing the config.

Check if config file already exists:

cat <CONFIG_PATH> 2>/dev/null || echo "CONFIG_NOT_FOUND"

• CONFIG_NOT_FOUND: Create with config below.
• Exists, no

  tooluniverse

  entry: Merge the

  tooluniverse

  block into the existing

  mcpServers

  .
• Already has

  tooluniverse

  : "ToolUniverse is already configured — I'll skip rewriting to avoid overwriting any API keys." Only overwrite if user asks.

Ask: "Would you like ToolUniverse to auto-update whenever your app starts? (~1–2s startup overhead, recommended: yes)"

• Yes → use

  ["--refresh", "tooluniverse"]

  in args
• No → use

  ["tooluniverse"]

  ; upgrade manually with

  uv cache clean tooluniverse

Standard config (Cursor, Windsurf, Claude Code, Gemini CLI, Qwen Code, Cline):

{
  "mcpServers": {
    "tooluniverse": {
      "command": "uvx",
      "args": ["--refresh", "tooluniverse"],
      "env": {
        "PYTHONIOENCODING": "utf-8"
      }
    }
  }
}

One-liner to write or merge the config safely:

python3 -c "
import json, os
p = os.path.expanduser('CONFIG_PATH')
os.makedirs(os.path.dirname(p), exist_ok=True)
cfg = json.load(open(p)) if os.path.exists(p) else {}
cfg.setdefault('mcpServers', {})['tooluniverse'] = {
    'command': 'uvx', 'args': ['--refresh', 'tooluniverse'],
    'env': {'PYTHONIOENCODING': 'utf-8'}
}
json.dump(cfg, open(p, 'w'), indent=2)
print('Done — tooluniverse added to', p)
"

Replace

CONFIG_PATH

~/.cursor/mcp.json

~/.claude.json

.mcp.json

~/.codeium/windsurf/mcp_config.json

%USERPROFILE%\.codeium\windsurf\mcp_config.json

.vscode/mcp.json

"servers"

"mcpServers"

"type": "stdio"

codex mcp add tooluniverse -- uvx tooluniverse

opencode.json

"mcp"

~/.gemini/settings.json

~/.qwen/settings.json

cline_mcp_settings.json

~/.gemini/antigravity/mcp_config.json

%USERPROFILE%\.gemini\antigravity\mcp_config.json

For Codex and OpenCode special formats, read MCP_CONFIG.md.

VS Code / Copilot config — create

.vscode/mcp.json

{
  "servers": {
    "tooluniverse": {
      "command": "uvx",
      "args": ["--refresh", "tooluniverse"],
      "env": { "PYTHONIOENCODING": "utf-8" },
      "type": "stdio"
    }
  }
}

After saving

.vscode/mcp.json

tooluniverse

⏸️ After Step 2: Ask "Did the config file get written? Anything look wrong?" Wait before continuing.

Step 3 (coding use only): Install Python package

Skip if user only needs MCP. For scripting use:

pip install tooluniverse

Verify:

from tooluniverse import ToolUniverse
tu = ToolUniverse()
print(f"ToolUniverse version: {tu.__version__}")

⏸️ After Step 3 (if applicable): Ask "Did the import work?" Wait for the answer.

Step 4: Set up API Keys

Many tools work without keys, but some unlock powerful features. First, ask the user about their research interests to recommend only what's relevant. Use AskQuestion if available:

• Literature search & publications
• Drug discovery & pharmacology
• Protein structure & interactions
• Genomics & disease associations
• Rare diseases & clinical
• AI-powered analysis (needs LLM key)
• Not sure yet / skip for now

Fetch API_KEYS_REFERENCE.md to see the full list with registration steps. Map the user's research interest to 2–4 recommended keys from that file, then walk through them one at a time: explain what each unlocks → give the registration link → wait for them to get the key → help add it to the

env

"env": {
  "PYTHONIOENCODING": "utf-8",
  "NCBI_API_KEY": "your_key_here"
}

⏸️ After Step 4: Walk through one key at a time. After each key: "Got it? Want to add another, or skip for now?" Don't list all keys at once.

Step 5: Test & Status Check

Pre-flight check before restarting:

timeout 10 uvx tooluniverse --help

• Prints usage → proceed to restart.
• Fails → fix first (see TROUBLESHOOTING.md Issue 5). Don't restart yet.

Ask user to fully quit and reopen their app (⌘Q on Mac — closing the window is not enough).

⏱️ First launch takes 60–90 seconds while the app downloads and installs ToolUniverse. Claude Desktop only — watch logs while it loads:

tail -f ~/Library/Logs/Claude/mcp*.log          # macOS
tail -f ~/.config/Claude/logs/mcp*.log          # Linux

Look for

"tooluniverse" connected

What to look for in the app UI:

• Claude Desktop (newer): A "Search and tools" button or + icon in the chat input → click it →

  tooluniverse

  should appear in the connected tools list.
• Claude Desktop (older) / Cursor / Windsurf: 🔨 hammer icon at the bottom of the chat input → click to see available tools.
• Claude Code / Gemini CLI / Codex CLI: Run

  /mcp

  or

  mcp list

  .

Show this status summary and fill in each line:

Setup Status
─────────────────────────────────────
✅/❌  uv installed         (uvx --version)
✅/❌  ToolUniverse starts  (uvx tooluniverse --help)
✅/❌  MCP config created   (config file found)
✅/❌  Server visible       ("Search and tools" / 🔨 hammer / Settings → Developer → MCP Servers)
✅/❌  Test tool call works
⬜     Skills installed     (do Step 6 next — required)
⬜     API keys (optional — add anytime)
─────────────────────────────────────

Live test call (verifies MCP connection):

list_tools

or

execute_tool("PubMed_search_articles", {"query": "CRISPR", "max_results": 1})

Skill smoke test (verifies skills are installed — do after Step 6):

Say:

"Use the tooluniverse skill to research the drug metformin"

The

tooluniverse

If all ✅, celebrate! 🎉 If any ❌, jump to the matching issue in TROUBLESHOOTING.md.

⏸️ After Step 5: Ask "Do you see ToolUniverse in the tools list? Did the test call return anything?" Wait for confirmation — then immediately proceed to Step 6. Do not skip it. Skills are what transform ToolUniverse from a raw API layer into an intelligent research assistant.

Step 6: Install ToolUniverse Skills (Required)

Do not skip this step. Without skills, the user has 1000+ tools but no guidance on how to use them together. Skills are what transform ToolUniverse into an intelligent research assistant — each one knows exactly which tools to call, in what order, to produce a full evidence-graded report on drugs, targets, diseases, variants, genomics, and more.

Say this to the user (adapt to their language and research interest from Step 4):

"One more required step — installing ToolUniverse's 65+ research skills. Instead of calling tools manually, you just say 'Use the tooluniverse skill to research the drug metformin' or 'Use the tooluniverse skill to find genes associated with type 2 diabetes' and the right skill runs automatically. This takes under a minute."

Option A — User runs in terminal (quickest, cross-platform):

npx skills add mims-harvard/ToolUniverse --all

This auto-detects the client and installs into the correct directory. Ask the user to confirm it completed successfully.

Option B — If npx fails (corporate network, cert issues, or Windows proxy problems), use the manual git clone path.

bash (macOS/Linux):

git clone --depth 1 --filter=blob:none --sparse https://github.com/mims-harvard/ToolUniverse.git /tmp/tu-skills
cd /tmp/tu-skills && git sparse-checkout set skills
# Example for Cursor — check SKILLS_CATALOG.md for other clients:
mkdir -p .cursor/skills && cp -r /tmp/tu-skills/skills/* .cursor/skills/
rm -rf /tmp/tu-skills

PowerShell (Windows):

# Run each line separately — PowerShell does not support && like bash
git clone --depth 1 --filter=blob:none --sparse https://github.com/mims-harvard/ToolUniverse.git "$env:TEMP\tu-skills"
Set-Location "$env:TEMP\tu-skills"
git sparse-checkout set skills
# Example for Cursor — check SKILLS_CATALOG.md for other clients:
New-Item -ItemType Directory -Force ".cursor\skills" | Out-Null
robocopy "$env:TEMP\tu-skills\skills" ".cursor\skills" /E
Remove-Item -Recurse -Force "$env:TEMP\tu-skills"

Find the right skills directory for the user's client in SKILLS_CATALOG.md.

Verify skills were installed — run in terminal (replace

SKILLS_DIR

bash (macOS/Linux):

ls SKILLS_DIR | grep tooluniverse

PowerShell (Windows):

Get-ChildItem "SKILLS_DIR" | Where-Object { $_.Name -like "*tooluniverse*" }

✅ Pass: You see folders like

tooluniverse

tooluniverse-drug-research

Smoke test — once directory check passes, ask the user to say:

"Use the tooluniverse skill to research the drug metformin"

If the response comes back as plain text without tool calls, the skills directory is likely still wrong — re-check SKILLS_CATALOG.md.

⏸️ After Step 6: Don't just confirm installation — immediately ask the user what problem they want to solve. Say something like: "Skills are ready! What would you like to research? Tell me your topic — a drug, disease, gene, or research question — and I'll use the right skill to give you a full report." Then activate the matching skill based on their answer. This is the whole point of the setup.

Also say: "Whether setup went smoothly or you hit any bumps — your feedback helps improve ToolUniverse for everyone. You can share suggestions or report issues at https://github.com/mims-harvard/ToolUniverse/issues — even a quick note like 'Step 3 was confusing on Windows' is valuable."

Common Issues

uvx: command not found

curl -LsSf https://astral.sh/uv/install.sh | sh

brew install uv

env

SyntaxError

requires-python

uvx --python 3.12 tooluniverse --help

uv cache clean tooluniverse

uvx

Full diagnostics in TROUBLESHOOTING.md. To file a GitHub issue: fetch GITHUB_ISSUE.md.

What's Next?

Setup is complete. Explain to the user how to use ToolUniverse skills, then immediately ask what they want to research.

How skills work (tell the user this)

Skills activate automatically — the user just writes a natural language request. No special commands, no prefixes. Examples:

"Use the tooluniverse skill to research the drug metformin"

"Use the tooluniverse skill to research Alzheimer's disease"

"Use the tooluniverse skill to find known targets of imatinib"

"Use the tooluniverse skill to review literature on CRISPR in sickle cell"

"Use the tooluniverse skill to interpret EGFR L858R in lung cancer"

The skill reads the question, calls the right tools in the right order, and produces a full evidence-graded report. The user doesn't need to know which skill to pick — just ask the question.

Now ask the user

"What would you like to research first? Tell me a drug, disease, gene, or question and I'll generate a full report."

Take their answer and activate the

tooluniverse

The user can add more API keys or skills anytime.

Always encourage feedback — whether setup worked perfectly or had rough edges. Say:

"We'd love to hear how setup went for you — smooth or bumpy. Share feedback or suggestions at https://github.com/mims-harvard/ToolUniverse/issues. You don't need to be a developer; a quick note about what was confusing or what worked well is genuinely helpful."

For unresolved failures: fetch and follow GITHUB_ISSUE.md to compose and submit a detailed report.