MCP Support

ToolUniverse runs as a Model Context Protocol server, exposing 1000+ scientific tools to any MCP-compatible AI client.

For platform-specific setup, see Set Up ToolUniverse.

Server Commands

Two server executables are available:

tooluniverse-smcp

Full-featured server with configurable transport (HTTP, SSE, stdio).

tooluniverse-smcp-stdio

Optimized for desktop AI clients (Claude Desktop, Cursor, etc.) via stdio.

CLI Options

tooluniverse-smcp [OPTIONS]

--port INT                     Server port (HTTP/SSE). Default: 8000
--host TEXT                    Bind host. Default: 0.0.0.0
--transport [http|stdio|sse]   Transport protocol. Default: http
--name TEXT                    Server display name
--max-workers INT              Worker pool size
--verbose                      Enable verbose logs

# Tool selection
--categories STR...            Include only these categories
--exclude-categories STR...    Exclude these categories
--include-tools STR...         Include only these tool names
--tools-file PATH              File with one tool name per line
--include-tool-types STR...    Include only these tool types
--exclude-tool-types STR...    Exclude these tool types
--tool-config-files TEXT       Mapping like "custom:/path/to/custom.json"

# Compact mode
--compact-mode                 Expose only core tools (reduces context usage)

# Hooks
--hooks-enabled                Enable output processing hooks
--hook-type [SummarizationHook|FileSaveHook]
--hook-config-file PATH        JSON config for hooks

tooluniverse-smcp-stdio [OPTIONS]

--name TEXT                    Server display name
--categories STR...            Include only these categories
--include-tools STR...         Include only these tool names
--tools-file PATH              File with one tool name per line
--include-tool-types STR...    Include only these tool types
--exclude-tool-types STR...    Exclude these tool types
--compact-mode                 Expose only core tools
--hooks                        Enable hooks
--hook-type [SummarizationHook|FileSaveHook]
--hook-config-file PATH        JSON config for hooks

Configuration Files

Tools file — one tool name per line, # for comments:

# tools.txt
OpenTargets_get_associated_targets_by_disease_efoId
Tool_Finder_LLM
ChEMBL_search_similar_molecules

Pass with --tools-file tools.txt.

Hook config file:

{
  "SummarizationHook": {
    "max_tokens": 2048,
    "summary_style": "concise"
  },
  "FileSaveHook": {
    "output_dir": "/tmp/tu_outputs",
    "filename_template": "{tool}_{timestamp}.json"
  }
}

Pass with --hook-config-file hooks.json.

Python Client Example

import requests

tools = requests.get("http://127.0.0.1:8000/mcp/tools").json()

result = requests.post("http://127.0.0.1:8000/mcp/run", json={
    "name": "UniProt_get_entry_by_accession",
    "arguments": {"accession": "P04637"}
}).json()

Advanced Features