drug-discovery-prompts/upstream/mims-harvard-ToolUniverse/skills/setup-tooluniverse/TROUBLESHOOTING.md

title, task, lineage_type, upstream_source, upstream_sha, imported_at, prompt_class, upstream_changes, author, validated

title	task	lineage_type	upstream_source	upstream_sha	imported_at	prompt_class	upstream_changes	author	validated
Troubleshooting ToolUniverse Setup		import	https://github.com/mims-harvard/ToolUniverse/blob/e2520a96/skills/setup-tooluniverse/TROUBLESHOOTING.md	e2520a96	2026-06-26	prompt	accepted	upstream	false

Troubleshooting ToolUniverse Setup

When something fails, always provide the exact copy-paste fix command — don't just say "check the logs."

Issue 1: Python Version Incompatibility

Symptom: Error containing requires-python = ">=3.10" or Python 3.9 is not supported

Fix:

brew install [email protected]        # macOS
# or: sudo apt install python3.12  # Ubuntu/Debian
python3.12 -m pip install tooluniverse

Issue 2: uvx or uv Not Found

Symptom: uvx: command not found or uv: command not found

Fix:

curl -LsSf https://astral.sh/uv/install.sh | sh
source ~/.zshrc 2>/dev/null || source ~/.bashrc 2>/dev/null
uvx --version   # verify it worked

Issue 3: Context Window Overflow

Symptom: MCP server loads but the client becomes very slow, or gives "context too large" errors

Note: Compact mode is already the default — the tooluniverse entry point enables it automatically. If still hitting context limits:

"args": ["--refresh", "tooluniverse", "--tool-categories", "uniprot,chembl,pubmed"]

Restart the app after editing.

Issue 4: Import Errors for Specific Tools

Symptom: Tool fails with ModuleNotFoundError: No module named 'rdkit' (or similar)

Fix:

pip install tooluniverse[all]
# Or the specific extra needed:
# pip install tooluniverse[visualization]   # rdkit, py3Dmol
# pip install tooluniverse[singlecell]       # cellxgene
# pip install tooluniverse[ml,embedding]     # sentence-transformers, admet-ai

Issue 5: MCP Server Won't Start

Symptom: No tooluniverse server in client's server list, "Failed to spawn process", "ENOENT", "command not found"

#1 most common cause — GUI apps (Claude Desktop, Windsurf) don't inherit shell PATH.

Option A — Homebrew (macOS, recommended, permanent):

brew install uv
# Then restart the app — can now use "uvx" everywhere, no absolute path needed

Option B — Symlink (macOS/Linux, permanent):

sudo ln -sf "$(which uvx)" /usr/local/bin/uvx   # Intel Mac / Linux
# OR for Apple Silicon Mac:
sudo ln -sf "$(which uvx)" /opt/homebrew/bin/uvx

Option C — Absolute path (all platforms, quick fix):

which uvx   # macOS/Linux → e.g. /opt/homebrew/bin/uvx or /Users/you/.local/bin/uvx
where uvx   # Windows

Use that full path as "command" in your config instead of "uvx".

Full diagnostic chain — run these in order:

# 1. Can uvx find and run it?
uvx tooluniverse --help

# 2. Does it start without errors? (Ctrl+C to stop)
uvx tooluniverse

# 3. Is the config file valid JSON?
python3 -m json.tool ~/.cursor/mcp.json   # replace path for your client

# 4. View the client's MCP logs
tail -50 ~/Library/Logs/Claude/mcp*.log 2>/dev/null        # Claude Desktop (macOS)
tail -50 ~/Library/Application\ Support/Cursor/logs/*.log  # Cursor (macOS)

Fix based on where the chain breaks. Other common causes: trailing commas in JSON, wrong config file path.

Issue 6: API Key Errors (401/403)

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

Diagnostic:

echo $NCBI_API_KEY    # replace with the failing key name

Common fixes:

• Keys must be in the "env" block in your MCP config file (not a .env file the app doesn't load):

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

• Wrong key name: variable must match exactly (e.g., ONCOKB_API_TOKEN not ONCOKB_API_KEY)
• Restart required after editing the config file
• Free tier pending: DisGeNET and OMIM may take 24–48h for account approval

Issue 7: Upgrading ToolUniverse

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

The recommended config uses "--refresh" which auto-updates on every launch. If the user's config doesn't have it:

"args": ["--refresh", "tooluniverse"]

To upgrade immediately:

uv cache clean tooluniverse   # clears uvx cache, then restart the MCP client

To pin a specific version:

"args": ["tooluniverse==1.0.19"]

For pip users:

pip install --upgrade tooluniverse

Issue 8: Python Version Too New

Symptom: Errors like requires-python >=3.10,<3.14, SyntaxError in ToolUniverse code, or ModuleNotFoundError for a built-in module after upgrading Python.

ToolUniverse supports Python 3.10–3.13. Python 3.14+ (pre-release) may break things.

Check your Python version:

python3 --version
uvx tooluniverse --help   # see what Python uvx picks up

Fix — pin to a compatible Python for uvx:

uvx --python 3.12 tooluniverse --help

If that works, update your MCP config to use the pinned version:

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

Issue 9: Stale or Broken Package Version

Symptom: A tool that used to work now errors, or a new tool listed in docs isn't available, or you see AttributeError / ImportError referencing ToolUniverse internals.

Step 1 — force a fresh install:

uv cache clean tooluniverse
uvx tooluniverse --version   # should pull the latest

Step 2 — check what version is running:

uvx tooluniverse --version

Step 3 — pin to latest stable if auto-update pulls a broken release:

# In your MCP config args:
"args": ["tooluniverse==<last-known-good-version>"]
# Check releases: https://github.com/mims-harvard/ToolUniverse/releases

Still Stuck? File a GitHub Issue

If none of the above fixes it, open a GitHub issue. Run this script first — it collects system info with no personal data (paths and usernames are stripped):

python3 - << 'EOF'
import sys, platform, subprocess, os, re, urllib.parse

home = os.path.expanduser("~")
def run(cmd):
    try:
        out = subprocess.check_output(cmd, shell=True, stderr=subprocess.STDOUT, text=True).strip()
    except Exception as e:
        out = f"error: {e}"
    return re.sub(re.escape(home), "~", out)

lines = [
    "**Environment**",
    f"- OS: {platform.system()} {platform.release()} {platform.machine()}",
    f"- Python: {sys.version.split()[0]}",
    f"- uv: {run('uv --version')}",
    f"- uvx: {run('uvx --version')}",
    f"- ToolUniverse: {run('uvx tooluniverse --version 2>/dev/null || echo unknown')}",
    "",
    "**Steps to reproduce**",
    "1. <describe what you did>",
    "",
    "**Error message**",
    "```",
    "<paste full error here>",
    "```",
    "",
    "**Expected behavior**",
    "<what you expected to happen>",
]

body = "\n".join(lines)
title = "Bug: <brief description>"
url = ("https://github.com/mims-harvard/ToolUniverse/issues/new"
       "?title=" + urllib.parse.quote(title)
       + "&body=" + urllib.parse.quote(body))

print("=" * 60)
print("ISSUE BODY (copy-paste if opening manually):")
print("=" * 60)
print(body)
print()
print("=" * 60)
print("PRE-FILLED ISSUE URL (open in browser):")
print("=" * 60)
print(url)
EOF

The script prints two things:

1. Issue body — copy-paste it into https://github.com/mims-harvard/ToolUniverse/issues/new
2. Pre-filled URL — open it in a browser to get a GitHub issue form with the info already filled in

If GitHub CLI (gh) is installed, you can create the issue directly — paste the body from above, then run:

gh issue create --repo mims-harvard/ToolUniverse \
  --title "Bug: <brief description>" \
  --body "<paste issue body here>"

You can also email Shanghua Gao with the issue body.