Server Mode¶

ToolRegistry Hub can expose every tool as a network endpoint — either an OpenAPI (REST) server or an MCP server. Both modes auto-register all available tools; you just pick the protocol and start.

Installation¶

# Full server (OpenAPI + MCP, Python 3.10+)
pip install toolregistry-hub[server]

# OpenAPI only
pip install toolregistry-hub[server_openapi]

# MCP only (Python 3.10+)
pip install toolregistry-hub[server_mcp]

Start the Server¶

OpenAPI¶

toolregistry-hub openapi --host 0.0.0.0 --port 8000

After startup:

• API root: http://localhost:8000
• Interactive docs: http://localhost:8000/docs
• OpenAPI spec: http://localhost:8000/openapi.json

MCP¶

# Streamable HTTP (recommended for remote clients)
toolregistry-hub mcp --transport streamable-http --host 0.0.0.0 --port 8000

# SSE transport
toolregistry-hub mcp --transport sse --host 0.0.0.0 --port 8000

# Stdio transport (for local agent integration)
toolregistry-hub mcp --transport stdio

Authentication¶

The server supports optional Bearer Token authentication.

Setup¶

export API_BEARER_TOKEN="your-secret-token"

export API_BEARER_TOKEN="token1,token2,token3"

export API_BEARER_TOKENS_FILE="/path/to/tokens.txt"

Usage¶

Authorization: Bearer your-valid-token

If no token variables are set, authentication is disabled.

Tool Configuration¶

Control which tools are loaded with a tools.jsonc file:

# Auto-discovered from working directory
cp tools.jsonc.example tools.jsonc

# Or specify via CLI
toolregistry-hub openapi --config path/to/tools.jsonc

Denylist Mode (Default)¶

{
  "mode": "denylist",
  "disabled": ["file_ops"]  // disable specific tools
}

Allowlist Mode¶

{
  "mode": "allowlist",
  "enabled": ["calculator", "datetime", "unit_converter"]
}

Custom Tool Registration¶

{
  "tools": [
    {"class": "toolregistry_hub.calculator.Calculator", "namespace": "calculator"},
    {"class": "my_package.MyTool", "namespace": "my_tool"}
  ]
}

Calling the API¶

curl¶

curl -X POST "http://localhost:8000/tools/calculator/evaluate" \
  -H "Content-Type: application/json" \
  -d '{"expression": "2 + 2 * 3"}'

Python¶

import requests

response = requests.post(
    "http://localhost:8000/tools/calculator/evaluate",
    json={"expression": "2 + 2 * 3"}
)
print(response.json())

Error Handling¶

Standard HTTP status codes:

Error responses return {"detail": "Error description"}.

Troubleshooting¶

See Also¶

• CLI Reference — all command-line options
• API Endpoints — full endpoint listing
• Docker Deployment — containerized setup
• Environment Variables — every env var in one place