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:

bash

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:

bash

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)

json

{
  "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)

json

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

Config File Locations by Client

Client	Config File (macOS)	How to Access
Cursor	`~/.cursor/mcp.json`	Settings → MCP → Add new global MCP server
Claude Desktop	`~/Library/Application Support/Claude/claude_desktop_config.json`	Settings → Developer → Edit Config
Claude Code	`~/.claude.json` (user) or `.mcp.json` (project)	`claude mcp add` CLI or edit directly
Windsurf	`~/.codeium/windsurf/mcp_config.json`	Click MCP hammer icon → Configure
VS Code (Copilot)	`.vscode/mcp.json` (workspace) or user profile `mcp.json`	Cmd Palette → "MCP: Add Server" (see different format below)
Cline	`cline_mcp_settings.json` (in VS Code extension globalStorage)	Cline panel → MCP Servers → Configure
Codex (OpenAI)	`~/.codex/config.toml`	Create/edit manually (TOML format, see below)
Gemini CLI	`~/.gemini/settings.json` (user) or `.gemini/settings.json` (project)	`gemini mcp add` CLI or edit directly
Antigravity	`mcp_config.json`	"..." dropdown → Manage MCP Servers → View raw config
Trae	`.trae/mcp.json` (project) or global via Trae UI	Ctrl+U → AI Management → MCP → Configure Manually
OpenCode	`~/.config/opencode/opencode.json` or `opencode.json` (project)	Edit directly

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

json

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

Codex (TOML format) -- add to

~/.codex/config.toml

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

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:

bash

pip install tooluniverse

Then verify together:

python

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

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
Map their answer to recommended keys using the tiers below. Don't overwhelm -- suggest 2-4 keys to start.
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
After all keys are added, restart the app and test one key with a real tool call.
Let them know they can always come back to add more keys later.

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

Key	Service	What It Unlocks	Free?	Registration
`NCBI_API_KEY`	NCBI/PubMed	PubMed literature search (raises rate limit 3->10 req/s)	Yes	https://account.ncbi.nlm.nih.gov/settings/
`NVIDIA_API_KEY`	NVIDIA NIM	16 tools: AlphaFold2 structure prediction, molecular docking, genomics	Yes	https://build.nvidia.com
`BIOGRID_API_KEY`	BioGRID	Protein-protein interaction queries	Yes	https://webservice.thebiogrid.org/
`DISGENET_API_KEY`	DisGeNET	5 gene-disease association tools	Yes (academic)	https://disgenet.com/academic-apply

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

Key	Service	What It Unlocks	Free?	Registration
`OMIM_API_KEY`	OMIM	4 Mendelian/rare disease tools	Yes	https://omim.org/api
`ONCOKB_API_TOKEN`	OncoKB	Precision oncology annotations	Yes (academic)	https://www.oncokb.org/apiAccess
`UMLS_API_KEY`	UMLS/NLM	5 medical terminology & concept mapping tools	Yes	https://uts.nlm.nih.gov/uts/
`USPTO_API_KEY`	USPTO	6 patent search & analysis tools	Yes	https://account.uspto.gov/api-manager/
`SEMANTIC_SCHOLAR_API_KEY`	Semantic Scholar	Literature search (raises rate limit 1->100 req/s)	Yes	https://www.semanticscholar.org/product/api
`FDA_API_KEY`	openFDA	Drug/food/device adverse event queries (raises limit 240->1000 req/min)	Yes	https://open.fda.gov/apis/authentication/
`BRENDA_EMAIL` + `BRENDA_PASSWORD`	BRENDA	3 enzyme database tools (both email and password required)	Yes	https://brenda-enzymes.org/register.php

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.

Key	Service	What It Unlocks	Free Tier?	Registration
`GEMINI_API_KEY`	Google Gemini	Agentic tools via Gemini (good free tier)	Yes	https://aistudio.google.com/apikey
`OPENROUTER_API_KEY`	OpenRouter	Agentic tools via 100+ LLM models	Pay-per-use	https://openrouter.ai/
`OPENAI_API_KEY`	OpenAI	Embedding features, LLM-based tool finding	Pay-per-use	https://platform.openai.com/
`AZURE_OPENAI_API_KEY`	Azure OpenAI	Agentic tools via Azure (enterprise)	Pay-per-use	Azure Portal
`ANTHROPIC_API_KEY`	Anthropic Claude	Claude-based features	Pay-per-use	https://console.anthropic.com/
`HF_TOKEN`	HuggingFace	Model/dataset access, HF Inference API	Yes	https://huggingface.co/settings/tokens

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:

json

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

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:

Restart the app (Cursor/Claude Desktop/etc.) so the new MCP config is picked up
Check the MCP server appears in the server list

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

Skill	What It Does
`tooluniverse`	General strategies for using 1200+ tools effectively
`tooluniverse-drug-research`	Comprehensive drug profiling (identity, pharmacology, safety, ADMET)
`tooluniverse-target-research`	Drug target intelligence (structure, interactions, druggability)
`tooluniverse-disease-research`	Systematic disease analysis across 10 research dimensions
`tooluniverse-literature-deep-research`	Thorough literature reviews with evidence grading
`tooluniverse-drug-repurposing`	Find new therapeutic uses for existing drugs
`tooluniverse-precision-oncology`	Mutation-based treatment recommendations for cancer
`tooluniverse-rare-disease-diagnosis`	Phenotype-to-diagnosis for suspected rare diseases
`tooluniverse-pharmacovigilance`	Drug safety signal analysis from FDA adverse event data
`tooluniverse-infectious-disease`	Rapid pathogen characterization & drug repurposing
`tooluniverse-protein-structure-retrieval`	Protein 3D structure retrieval & quality assessment
`tooluniverse-sequence-retrieval`	DNA/RNA/protein sequence retrieval from NCBI/ENA
`tooluniverse-chemical-compound-retrieval`	Chemical compound data from PubChem/ChEMBL
`tooluniverse-expression-data-retrieval`	Gene expression & omics datasets
`tooluniverse-variant-interpretation`	Genetic variant clinical interpretation
`tooluniverse-protein-therapeutic-design`	AI-guided protein therapeutic design
`tooluniverse-binder-discovery`	Small molecule binder discovery via virtual screening
`tooluniverse-sdk`	Build research pipelines with the Python SDK
`setup-tooluniverse`	This setup guide

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:

bash

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

bash

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

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

bash

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

Codex (OpenAI) -- uses

.agents/skills/

directory (auto-discovered):

bash

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

Gemini CLI -- uses

.gemini/skills/

directory (auto-discovered):

bash

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

Claude Code -- uses

.claude/skills/

directory (auto-discovered):

bash

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

OpenCode -- uses

.opencode/skills/

directory (auto-discovered):

bash

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

Trae -- supports skills via

.trae/skills/

bash

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:

bash

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

Clean up after copying:

bash

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:

Test command directly:

bash

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

Check JSON syntax in mcp.json (no trailing commas, proper quotes)

View Cursor logs:

~/Library/Application Support/Cursor/logs/

(macOS)

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:

bash

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

json

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

For pip users:

bash

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

setup-tooluniverse

NPX Install

Tags

SKILL.md Content

Setup ToolUniverse

Agent Behavior

Internal Notes (do not show to user)

Step 0: Welcome & Discovery

Installation Workflow

Step 1: Make sure uv is installed

Step 2: Add ToolUniverse to your MCP config

MCP Server Configuration (same for all clients)

Config File Locations by Client

Clients with Different Config Formats

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

Step 4: Set up API Keys

How to guide API key setup

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)

Adding Keys to Configuration

Verify keys work

Step 5: Test it together

Step 6: Install ToolUniverse Skills (Highly Recommended)

Available Skills

How to Install Skills

How to Use Skills

Common Issues & Solutions

Issue 1: Python Version Incompatibility

Issue 2: uvx or uv Not Found

Issue 3: Context Window Overflow

Issue 4: Import Errors for Specific Tools

Issue 5: MCP Server Won't Start

Issue 6: API Key Errors (401/403)

Issue 7: Upgrading ToolUniverse

Still stuck?

What's Next?

Quick Reference