Overview

The Hypertool MCP Server lets you group and swap sets of tools (personas) at runtime for agents that use the Model Context Protocol (MCP). Instead of giving an agent access to a single large pool of tools, you define smaller, role-oriented toolsets (personas) and switch between them dynamically. This reduces cognitive load, limits accidental tool usage, and speeds up tool discovery for downstream systems.

This server acts as a lightweight MCP-compatible registry and switchboard. It exposes tool manifests and persona definitions, serves tool metadata to clients, and provides hot-swap operations so you can change what tools are available to an agent without restarting the agent or reloading the full tool registry.

Features

Persona-based tool grouping: define role-specific toolsets (e.g., “researcher”, “deployer”, “analyst”)
Hot-swappable personas: change active toolsets at runtime with API calls
Lightweight MCP-compatible endpoints for tool and persona discovery
Tool metadata manifests (name, description, input/output schema, method)
Example persona and tool manifests included in repo for quick startup
Simple HTTP API for integration with LLM agents, orchestrators, or test harnesses
Optional Docker support for easy deployment

Installation / Configuration

Prerequisites: Docker (optional) and a recent Node.js / Python runtime if running from source (see repository for exact runtime).

Quick start with Docker:

# Pull and run the image (replace with official image name if available)
docker run -p 8080:8080 ghcr.io/toolprint/hypertool-mcp:latest

Run from source (generic example):

git clone https://github.com/toolprint/hypertool-mcp.git
cd hypertool-mcp
# Install dependencies (example; the repo will include exact instructions)
npm install
# Start the server
npm run start

Environment variables (examples — actual variables are listed in the repo):

# Example env values
MCP_PORT=8080
MCP_HOST=0.0.0.0
MCP_DATA_DIR=./data   # persona and tool manifests
MCP_LOG_LEVEL=info

Configuration files

persona manifests: JSON files describing named toolsets
tool manifests: JSON describing each tool’s metadata and endpoint Place manifests in the configured data directory or register them via the server API.

Available Resources

The repository contains a set of example resources to get started quickly:

sample/personas/*.json — persona definitions showing which tools are included
sample/tools/*.json — example tool manifests with metadata and schemas
examples/requests.md — curl and HTTP examples for common interactions
Dockerfile and a simple startup script for quick deployment

Typical tool manifest fields (table)

Field	Type	Description
name	string	Human-readable tool name
id	string	Unique identifier
description	string	Short description of what the tool does
method	string	HTTP method or invocation type
endpoint	string	URL or routing key to invoke the tool
input_schema	object	JSON Schema for input validation (optional)
output_schema	object	JSON Schema for output (optional)

Typical persona manifest includes:

id, name, description
list of tool ids to include
optional metadata (roles, ttl, permissions)

API Examples

List tools:

curl http://localhost:8080/mcp/tools

List personas:

curl http://localhost:8080/mcp/personas

Activate (swap) a persona:

curl -X POST http://localhost:8080/mcp/persona/swap \
  -H "Content-Type: application/json" \
  -d '{"persona_id":"researcher-v1", "target_agent":"agent-123"}'

curl -X POST http://localhost:8080/mcp/tools \
  -H "Content-Type: application/json" \
  -d @sample/tools/my-tool.json

Adjust these endpoints per the server’s README — the repo includes concrete API documentation and example requests.

Use Cases

Toolset reduction for safer agents: Limit an LLM agent to only the tools needed for a task (e.g., file search + summarizer for research), then swap to a different persona for deployment tasks (e.g., build + deploy).
Multi-tenant orchestration: Different customers or sessions can have different active personas, isolating capabilities and complying with least-privilege policies.
Rapid testing and QA: Swap personas to validate agent behavior against different toolsets without redeploying or changing agent code.
Role-based assistant behavior: Provide a single assistant that behaves differently for roles (support, admin, analyst) by switching the active persona based on user identity or context.
Progressive tool rollouts: Gradually expose new tools to a subset of agents by creating a persona containing new tools and enabling it for a controlled cohort.

Getting Help and Next Steps

Repository and issues: https://github.com/toolprint/hypertool-mcp
Read the repo’s examples directory for concrete manifests and curl samples
Try converting an existing tool registry into persona manifests to see immediate benefits in agent behavior and tool discoverability

Start by examining the sample persona and tool JSON files, run the server locally (or via Docker), and experiment with the swap API to see how hot-swappable personas simplify tool management.

Hypertool MCP Server: Hot-Swappable Persona Toolsets