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

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

uvx

For coding use, also ask about Python version (

python3 --version

Installation Workflow

Step 1: Make sure uv is installed

First, check if the user already has

uv

which uv || echo "uv not installed"

If it's already installed, let them know and move on. If not, explain that

uv

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

tooluniverse

--compact-mode

pip install

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

~/.cursor/mcp.json

~/Library/Application Support/Claude/claude_desktop_config.json

~/.claude.json

.mcp.json

claude mcp add

~/.codeium/windsurf/mcp_config.json

.vscode/mcp.json

mcp.json

cline_mcp_settings.json

~/.codex/config.toml

~/.gemini/settings.json

.gemini/settings.json

gemini mcp add

mcp_config.json

.trae/mcp.json

~/.config/opencode/opencode.json

opencode.json

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

Most clients use the same JSON

mcpServers

"servers"

"mcp"

Clients with Different Config Formats

VS Code (Copilot) -- uses

"servers"

"mcpServers"

"type"

.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

type

command

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

pip install

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)

NCBI_API_KEY

NVIDIA_API_KEY

BIOGRID_API_KEY

DISGENET_API_KEY

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

OMIM_API_KEY

ONCOKB_API_TOKEN

UMLS_API_KEY

USPTO_API_KEY

SEMANTIC_SCHOLAR_API_KEY

FDA_API_KEY

BRENDA_EMAIL

BRENDA_PASSWORD

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.

GEMINI_API_KEY

OPENROUTER_API_KEY

OPENAI_API_KEY

AZURE_OPENAI_API_KEY

ANTHROPIC_API_KEY

HF_TOKEN

Adding Keys to Configuration

Best approach: Add to the

env

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

Alternative: Create a

.env

KEY=value

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})

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

tooluniverse

tooluniverse-drug-research

tooluniverse-target-research

tooluniverse-disease-research

tooluniverse-literature-deep-research

tooluniverse-drug-repurposing

tooluniverse-precision-oncology

tooluniverse-rare-disease-diagnosis

tooluniverse-pharmacovigilance

tooluniverse-infectious-disease

tooluniverse-protein-structure-retrieval

tooluniverse-sequence-retrieval

tooluniverse-chemical-compound-retrieval

tooluniverse-expression-data-retrieval

tooluniverse-variant-interpretation

tooluniverse-protein-therapeutic-design

tooluniverse-binder-discovery

tooluniverse-sdk

setup-tooluniverse

How to Install Skills

Skills are in the

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/

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/

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

Gemini CLI -- uses

.gemini/skills/

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

Claude Code -- uses

.claude/skills/

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

OpenCode -- uses

.opencode/skills/

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"

brew install python@3.12

python3.12 -m pip install tooluniverse

Issue 2: uvx or uv Not Found

Symptom:

uvx: command not found

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

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]

[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

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

Then restart the MCP client.

uvx

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

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