promptadmin/drug-discovery-prompts
1
0
Fork 0
Code Issues Pull Requests 29 Packages Projects Releases Wiki Activity
Files
upstream-sync/scientific-agent-skills-20260706-4d97e2-ulgb
drug-discovery-prompts/upstream/mims-harvard-ToolUniverse/skills/setup-tooluniverse/MCP_CONFIG.md
T

12 KiB
Raw Permalink Blame History

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
MCP Configuration Guide import https://github.com/mims-harvard/ToolUniverse/blob/e2520a96/skills/setup-tooluniverse/MCP_CONFIG.md e2520a96 2026-06-26 prompt accepted upstream false

MCP Configuration Guide

Advanced configuration options for ToolUniverse MCP integration.

Configuration File Locations

Cursor

  • Global (all workspaces) — macOS/Linux: ~/.cursor/mcp.json · Windows: %USERPROFILE%\.cursor\mcp.json
  • Project-level (single workspace): .cursor/mcp.json in the project root — can be committed to version control for team sharing

Claude Desktop

  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
  • Windows: %APPDATA%\Claude\claude_desktop_config.json
  • Linux: ~/.config/Claude/claude_desktop_config.json

VS Code / Copilot

  • Project-level (workspace root): .vscode/mcp.json
  • Note: VS Code uses "servers" key (not "mcpServers") and requires "type": "stdio" — see the VS Code template below.

Windsurf

  • macOS/Linux: ~/.codeium/windsurf/mcp_config.json
  • Windows: %USERPROFILE%\.codeium\windsurf\mcp_config.json

Claude Code

  • Global: ~/.claude.json
  • Project-level: .mcp.json in the project root

Gemini CLI

  • ~/.gemini/settings.json

Antigravity

  • macOS/Linux: ~/.gemini/antigravity/mcp_config.json
  • Windows: %USERPROFILE%\.gemini\antigravity\mcp_config.json

Access via: Agent Panel → "..." → Manage MCP Servers → View raw config. Uses "mcpServers" key (same as Claude Desktop format).

Cline

Full path to cline_mcp_settings.json varies by OS:

  • macOS: ~/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json
  • Linux: ~/.config/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json
  • Windows: %APPDATA%\Code\User\globalStorage\saoudrizwan.claude-dev\settings\cline_mcp_settings.json
  • Cline CLI (standalone): ~/.cline/data/settings/cline_mcp_settings.json

Access via Cline's "MCP Servers" icon → Configure tab → "Configure MCP Servers". Uses "mcpServers" key (same as Claude Desktop format).

Trae

  • Windows: %APPDATA%\Trae\User\mcp.json
  • macOS: ~/Library/Application Support/Trae/User/mcp.json
  • Linux: ~/.config/Trae/User/mcp.json

Verify the exact path in Trae: Settings → MCP → Open config file.

The AI agent can only access the global config. Project-level .trae/mcp.json is an experimental/beta feature and is not accessible to the agent — do not use it for MCP server registration.

For full Trae setup instructions (including manual write fallback and verification), see TRAE.md.

Configuration Templates

Basic Configuration (Recommended)

Zero-install setup using uvx (auto-downloads and runs ToolUniverse):

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

--refresh keeps ToolUniverse auto-updated on each startup (~1–2s overhead). Remove it to pin to the cached version and update manually with uv cache clean tooluniverse.

pip-Based Configuration (Alternative)

If you have ToolUniverse installed via pip install tooluniverse, you can use the installed command directly:

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

Development Configuration

Using development installation:

{
  "mcpServers": {
    "tooluniverse": {
      "command": "python3",
      "args": [
        "-m",
        "tooluniverse.smcp_server",
        "--compact-mode"
      ],
      "cwd": "/path/to/ToolUniverse-main"
    }
  }
}

VS Code / Copilot Configuration

VS Code uses a different schema. Create .vscode/mcp.json in the workspace root:

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

Key differences from standard config: uses "servers" (not "mcpServers") and requires "type": "stdio". After saving, fully restart VS Code and open Copilot Chat in that workspace.

Configuration Options

Compact Mode (Default with uvx)

When using uvx tooluniverse, compact mode is enabled by default — no flag needed. It exposes only 5 core tools to prevent context overflow, while keeping all 1000+ tools accessible via execute_tool.

If using the pip-based tooluniverse-smcp-stdio command, pass --compact-mode explicitly:

"args": ["--compact-mode"]

Core tools exposed in compact mode:

  • list_tools - List all available tools
  • grep_tools - Search tools by keyword
  • get_tool_info - Get tool details
  • execute_tool - Execute any tool by name
  • find_tools - Find tools by description

Specific Categories

Load only specific tool categories:

"args": [
  "--categories",
  "uniprot",
  "ChEMBL",
  "opentarget",
  "pdb"
]

Available categories: Run uvx tooluniverse --list-categories to see all.

Warning: Multiple categories may still cause context issues.

Exclude Categories

Load all except specific categories:

"args": [
  "--exclude-categories",
  "mcp_auto_loader_boltz",
  "mcp_auto_loader_expert_feedback"
]

Specific Tools Only

Load only named tools:

"args": [
  "--include-tools",
  "UniProt_get_entry_by_accession",
  "ChEMBL_get_molecule_by_chembl_id"
]

Enable Hooks

Enable output processing hooks (disabled by default for stdio):

"args": [
  "--refresh", "tooluniverse",
  "--hooks",
  "--hook-type",
  "SummarizationHook"
]

Hook types:

  • SummarizationHook - Summarize long outputs
  • FileSaveHook - Save outputs to files

Verbose Logging

Enable detailed logging for debugging:

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

Environment Variables

Standard Variables

"env": {
  "PYTHONIOENCODING": "utf-8",
  "PYTHONPATH": "/custom/python/path",
  "TOOLUNIVERSE_CACHE_DIR": "/custom/cache/dir"
}

API Keys

For tools requiring authentication:

"env": {
  "PYTHONIOENCODING": "utf-8",
  "OPENAI_API_KEY": "your-key-here",
  "ANTHROPIC_API_KEY": "your-key-here",
  "UMLS_API_KEY": "your-key-here"
}

Security Note: Avoid hardcoding keys. Use environment variables or .env files.

Better API Key Management

Use environment variables from shell:

"env": {
  "PYTHONIOENCODING": "utf-8",
  "OPENAI_API_KEY": "${OPENAI_API_KEY}"
}

Then set in shell:

export OPENAI_API_KEY=your-key-here

Multiple MCP Servers

Configure multiple servers:

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

Working Directory

Specify working directory:

{
  "mcpServers": {
    "tooluniverse": {
      "command": "uvx",
      "args": ["--refresh", "tooluniverse"],
      "env": { "PYTHONIOENCODING": "utf-8" },
      "cwd": "/path/to/working/directory"
    }
  }
}

Testing Configuration

Validate JSON

Before saving, validate JSON syntax:

# macOS/Linux
cat mcp.json | python3 -m json.tool

# Or use online validator

Test Command Directly

Test the MCP command in terminal:

uvx tooluniverse --help
# Should print usage text without errors

Test with a ToolUniverse Skill

After skills are installed (see SKILL.md Step 6), verify end-to-end by invoking the tooluniverse router skill in your prompt:

"Use the tooluniverse skill to research the drug metformin"

The tooluniverse skill is a router — it automatically picks the right sub-skill and calls multiple tools. Mentioning it explicitly ensures it activates on any client, since not all clients auto-detect skills from natural language alone.

If the response comes back as plain text without any tool calls, either skills are not installed, they are in the wrong directory, or the MCP server is not connected.

Other examples:

  • "Use the tooluniverse skill: what is known about Alzheimer's disease?"
  • "Use the tooluniverse skill: what does the literature say about CRISPR in cancer?"

Check Logs

After restarting application, check logs:

Cursor logs:

  • macOS: ~/Library/Application Support/Cursor/logs/
  • Look for files with "mcp" in the name

Claude Desktop logs:

  • Access via app: Help → View Logs

Troubleshooting Configuration

Issue: Server Won't Start

  1. Test command directly in terminal
  2. Check JSON syntax (no trailing commas)
  3. Verify paths are absolute, not relative
  4. Check file permissions

Issue: Context Overflow

  • Ensure --compact-mode is in args
  • Reduce number of categories
  • Use specific tools only

Issue: Command Not Found

  • Verify uvx works: uvx --version
  • Test ToolUniverse directly: uvx tooluniverse --help
  • If uvx is missing, install uv: curl -LsSf https://astral.sh/uv/install.sh | sh
  • For pip-based installs: pip show tooluniverse and which tooluniverse-smcp-stdio

Issue: Environment Variables Not Working

  • Use absolute paths
  • Avoid ~ expansion (use full path)
  • Check variable syntax in JSON

Performance Optimization

Fast Startup

Use minimal categories (compact mode is already the default):

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

Memory Optimization

Exclude heavy categories:

"args": [
  "--refresh", "tooluniverse",
  "--exclude-categories",
  "mcp_auto_loader_boltz"
]

Security Considerations

  1. API Keys: Never commit config files with hardcoded keys
  2. Paths: Use absolute paths to avoid ambiguity
  3. Permissions: Restrict config file permissions (chmod 600)
  4. Validation: Always validate JSON before saving

Example Configurations

Research Use Case

For scientific research with common tools:

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

Development Use Case

For tool development and testing:

{
  "mcpServers": {
    "tooluniverse-dev": {
      "command": "python3",
      "args": [
        "-m",
        "tooluniverse.smcp_server",
        "--compact-mode",
        "--verbose"
      ],
      "cwd": "/path/to/ToolUniverse-main"
    }
  }
}

Production Use Case

For production with specific tool categories:

{
  "mcpServers": {
    "tooluniverse-prod": {
      "command": "uvx",
      "args": [
        "tooluniverse",
        "--categories",
        "uniprot",
        "ChEMBL",
        "opentarget"
      ],
      "env": { "PYTHONIOENCODING": "utf-8" }
    }
  }
}

Advanced Features

Space Configuration

Load preset tool configurations:

"args": [
  "--compact-mode",
  "--load",
  "community/proteomics-toolkit"
]

Custom Hook Configuration

Use custom hook configuration file:

"args": [
  "--compact-mode",
  "--hooks",
  "--hook-config-file",
  "/path/to/hook_config.json"
]
Reference in New Issue View Git Blame Copy Permalink