Setup ToolUniverse

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

Agent Behavior

Be friendly, conversational, and interactive. This is a setup wizard, not a reference manual.

• 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).
• Go one step at a time. Don't dump all steps at once.
• Ask before proceeding to the next step. Confirm the previous step worked.
• Use the AskQuestion tool for structured choices when available (client selection, research areas, etc.).
• Explain briefly what each step does and why, in plain language.
• When something goes wrong, be reassuring and help troubleshoot before moving on.
• Celebrate small wins -- when uv installs successfully, when the MCP server appears, when the first tool call works.

Internal Notes (do not show to user)

⚠️ ToolUniverse has 1200+ tools which will cause context window overflow if all exposed directly. The default tooluniverse command already enables compact mode automatically.

Compact mode exposes only 5 core tools (list_tools, grep_tools, get_tool_info, execute_tool, find_tools) while keeping all 1200+ tools accessible via execute_tool.

Step 0: Welcome & Discovery

Start by welcoming the user and asking two questions to tailor the setup:

Question 1: Which app are you using?

Use AskQuestion if available:

• Cursor
• Claude Desktop
• VS Code / Copilot
• Windsurf
• Claude Code
• Gemini CLI
• Codex (OpenAI)
• Cline
• Trae
• Antigravity
• OpenCode
• Other

Question 2: How will you use ToolUniverse?

• MCP server (use scientific tools through chat) -- this is the default for most users
• Python coding (write scripts that import tooluniverse) -- also needs pip install

For MCP-only users, only uv is needed. uvx automatically installs and runs ToolUniverse.

For coding use, also ask about Python version (python3 --version, needs >=3.10, <3.14).

Installation Workflow

Step 1: Make sure uv is installed

First, check if the user already has uv (a fast Python package manager). Run this for them:

which uv || echo "uv not installed"

If it's already installed, let them know and move on. If not, explain that uv is a fast package manager that makes MCP setup simple, then install it:

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

Confirm it worked before moving to the next step.

Step 2: Add ToolUniverse to your MCP config

Now we'll add ToolUniverse to your app's MCP configuration. Based on the client the user chose in Step 0, help them find and edit the right config file. All clients use the same server config -- only the file location differs.

MCP Server Configuration (same for all clients)

Default method: Using uvx (Recommended)

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

uvx tooluniverse automatically installs and runs ToolUniverse with compact mode enabled by default (the tooluniverse entry point enables --compact-mode automatically). No separate pip install step required.

Alternative: Using a pre-installed command (if user already has ToolUniverse installed via pip)

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

Config File Locations by Client

Windows/Linux paths differ -- check your client's documentation for the exact location.

Most clients use the same JSON mcpServers format shown above. Exceptions: VS Code uses "servers" key, Codex uses TOML, and OpenCode uses a "mcp" key -- see below for their specific formats.

Clients with Different Config Formats

VS Code (Copilot) -- uses "servers" key (not "mcpServers") and requires "type" field. Add to .vscode/mcp.json:

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

Codex (TOML format) -- add to ~/.codex/config.toml:

[mcp_servers.tooluniverse]
command = "uvx"
args = ["tooluniverse"]
env = { "PYTHONIOENCODING" = "utf-8" }

OpenCode -- uses mcp key with type and command as array in opencode.json:

{
  "mcp": {
    "tooluniverse": {
      "type": "local",
      "command": ["uvx", "tooluniverse"],
      "enabled": true,
      "environment": { "PYTHONIOENCODING": "utf-8" }
    }
  }
}

Step 3 (Only if user chose coding use): Install Python package

Skip this if the user only needs MCP. For coding use, install into their Python environment:

pip install tooluniverse

Then verify together:

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

Let them know this is separate from the MCP server -- uvx installs into uv's cache, while pip install puts it in their Python environment for importing.

Step 4: Set up API Keys

Many tools work without API keys, but some unlock powerful features. Before diving into keys, ask the user about their research interests to recommend only what's relevant.

Read API_KEYS_REFERENCE.md for detailed per-key info (what it does, step-by-step registration, which tools need it).

How to guide API key setup

1. Ask the user what research areas they're interested in. Use AskQuestion if available with options like:

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

2. Map their answer to recommended keys using the tiers below. Don't overwhelm -- suggest 2-4 keys to start.

3. Walk through each key one at a time:

   • Explain in plain language what it unlocks (e.g., "This lets you search PubMed faster")
   • Give them the registration link
   • Wait for them to sign up and get the key
   • Help them add it to their config file
   • Move to the next key

4. After all keys are added, restart the app and test one key with a real tool call.

5. Let them know they can always come back to add more keys later.

Tier 1: Core Scientific Keys (Recommended for most users)

Tier 2: Specialized Scientific Keys (Based on research needs)

Tier 3: LLM Provider Keys (For agentic tool features)

At least one LLM key is needed for agentic features. The system tries providers in order: Azure OpenAI -> OpenRouter -> Gemini.

Adding Keys to Configuration

Best approach: Add to the env block in your MCP config file (the same file from Step 2). This way keys are passed directly to the MCP server:

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

Alternative: Create a .env file in your project directory with KEY=value pairs.

After adding keys: Restart the app for changes to take effect.

Verify keys work

Test each configured key with a real tool call:

• NCBI_API_KEY -> execute_tool("PubMed_search_articles", {"query": "CRISPR", "max_results": 1})
• NVIDIA_API_KEY -> execute_tool("NvidiaNIM_alphafold2_predict", {"sequence": "MKTVRQERLKS"})
• BIOGRID_API_KEY -> execute_tool("BioGRID_get_interactions", {"geneList": "TP53", "taxId": 9606})
• MOUSER_API_KEY -> execute_tool("Mouser_search_by_part_number", {"part_number": "STM32F103C8T6"})
• DIGIKEY_CLIENT_ID + DIGIKEY_CLIENT_SECRET -> execute_tool("DigiKey_search_by_keyword", {"keywords": "STM32"})

Step 5: Test it together

Time to see it in action! Ask the user to restart their app, then try a real tool call together:

1. Restart the app (Cursor/Claude Desktop/etc.) so the new MCP config is picked up
2. Check the MCP server appears in the server list
3. Run a test call -- suggest something relevant to their research interests:
   • General: grep_tools with keyword "protein" or list_tools
   • Literature: execute_tool("PubMed_search_articles", {"query": "CRISPR", "max_results": 1})
   • Drug discovery: execute_tool("ChEMBL_search_compound", {"query": "aspirin"})

If it works, celebrate and move to Step 6. If something goes wrong, check the Common Issues section below.

Step 6: Install ToolUniverse Skills (Highly Recommended)

Strongly recommend this step. Skills are pre-built research workflows that teach the AI how to conduct comprehensive scientific research -- they turn basic tool calls into expert-level investigations.

Explain to the user: "ToolUniverse comes with 19 research skills that act like expert guides. For example, the drug-research skill knows exactly which tools to call, in what order, to build a complete drug profile. Without skills, you'd need to figure out which of the 1200+ tools to use yourself."

Available Skills

How to Install Skills

Skills are in the skills/ folder of the ToolUniverse GitHub repo: https://github.com/mims-harvard/ToolUniverse/tree/main/skills

First, help the user download the skills:

# Clone just the skills folder from GitHub
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

Then install based on their client:

Cursor -- copy to .cursor/skills/ (auto-discovered):

mkdir -p .cursor/skills && cp -r /tmp/tu-skills/skills/* .cursor/skills/

Windsurf -- Cascade supports SKILL.md files the same way:

mkdir -p .windsurf/skills && cp -r /tmp/tu-skills/skills/* .windsurf/skills/

Codex (OpenAI) -- uses .agents/skills/ directory (auto-discovered):

mkdir -p .agents/skills && cp -r /tmp/tu-skills/skills/* .agents/skills/

Gemini CLI -- uses .gemini/skills/ directory (auto-discovered):

mkdir -p .gemini/skills && cp -r /tmp/tu-skills/skills/* .gemini/skills/

Claude Code -- uses .claude/skills/ directory (auto-discovered):

mkdir -p .claude/skills && cp -r /tmp/tu-skills/skills/* .claude/skills/

OpenCode -- uses .opencode/skills/ directory (auto-discovered):

mkdir -p .opencode/skills && cp -r /tmp/tu-skills/skills/* .opencode/skills/

Trae -- supports skills via .trae/skills/:

mkdir -p .trae/skills && cp -r /tmp/tu-skills/skills/* .trae/skills/

Cline / VS Code / Qwen -- copy skills into the project and reference as needed:

mkdir -p .skills && cp -r /tmp/tu-skills/skills/* .skills/

Clean up after copying:

rm -rf /tmp/tu-skills

How to Use Skills

Explain to the user:

• Skills activate automatically when the AI detects a relevant request
• The user can also trigger them explicitly, e.g., "Research the drug aspirin" will activate the drug-research skill
• Skills guide the AI through multi-step research workflows, calling the right tools in the right order
• The output is typically a comprehensive research report with evidence grading and source citations

Suggest a skill to try based on their research interests from Step 4. For example:

• "Try asking: 'Research the drug metformin' -- the drug-research skill will generate a full drug profile"
• "Try asking: 'What does the literature say about CRISPR in cancer?' -- the literature-deep-research skill will do a thorough review"

Common Issues & Solutions

Issue 1: Python Version Incompatibility

Symptom: requires-python = ">=3.10" error. Fix: brew install python@3.12 then python3.12 -m pip install tooluniverse

Issue 2: uvx or uv Not Found

Symptom: uvx: command not found. Fix: curl -LsSf https://astral.sh/uv/install.sh | sh then restart shell (source ~/.zshrc)

Issue 3: Context Window Overflow

Symptom: MCP server loads but Cursor/Claude becomes slow or errors

Solution: Enable compact mode (should already be set):

• Verify --compact-mode is in args
• Restart application
• Check you're using stdio command, not HTTP server

Issue 4: Import Errors for Specific Tools

Symptom: Some tools fail with ModuleNotFoundError

Solution: Install optional dependencies: pip install tooluniverse[all] (or specific extras like [singlecell], [ml,embedding], [visualization])

Issue 5: MCP Server Won't Start

Symptom: No tooluniverse server appears in Cursor/Claude

Diagnostic steps:

1. Test command directly:

   uvx tooluniverse
   # Should start without errors (Ctrl+C to exit)
   

2. Check JSON syntax in mcp.json (no trailing commas, proper quotes)
3. View Cursor logs: ~/Library/Application Support/Cursor/logs/ (macOS)
4. Verify file permissions on mcp.json

Issue 6: API Key Errors (401/403)

Symptom: Tool returns "unauthorized", "forbidden", or "invalid API key"

Common causes and fixes:

• Key not set: Check it's in the env block of mcp.json (or .env file) and app was restarted
• Wrong key name: Double-check the exact env variable name (e.g., ONCOKB_API_TOKEN not ONCOKB_API_KEY)
• Key expired or revoked: Log into the service and regenerate the key
• Copy-paste error: Make sure there are no extra spaces or newlines in the key value
• Free tier limits: Some services (DisGeNET, OMIM) require account approval before the key works

Issue 7: Upgrading ToolUniverse

Symptom: User wants a newer version, or tools are missing/outdated

uvx caches packages and may serve an older version. To upgrade:

# Clear the cached version and get the latest
uv cache clean tooluniverse

Then restart the MCP client. uvx will download the latest version on next start.

To pin a specific version:

"args": ["tooluniverse==1.0.18"]

For pip users:

pip install --upgrade tooluniverse

Still stuck?

If you run into an issue that can't be resolved with the steps above, encourage the user to open a GitHub issue at https://github.com/mims-harvard/ToolUniverse/issues or reach out to Shanghua Gao, the creator of ToolUniverse.

What's Next?

After setup is complete, suggest the user try one of these to get started:

• "Research the drug metformin" -- triggers the drug-research skill for a full drug profile
• "What are the known targets of imatinib?" -- triggers target-research
• "What does the literature say about CRISPR in sickle cell disease?" -- triggers literature-deep-research
• "Find protein structures for human EGFR" -- triggers protein-structure-retrieval

Point them to the tooluniverse general skill for tips on getting the most out of 1200+ tools, and remind them they can always come back to add more API keys or skills later.

Quick Reference

• Default setup: uvx tooluniverse -- auto-installs, auto-enables compact mode
• Upgrade: uv cache clean tooluniverse then restart the app
• First load: May take 30-60 seconds (downloads + installs); subsequent loads are fast
• All scientific API keys are free to obtain
• Agentic features need at least one LLM key (Gemini has a good free tier)
• Detailed API key docs: API_KEYS_REFERENCE.md
• Skills repo: https://github.com/mims-harvard/ToolUniverse/tree/main/skills
• Need help? Open a GitHub issue or email Shanghua Gao