hypertool-mcp
Dynamically expose tools from proxied servers based on an Agent Persona
Safety scan
A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.
Badge for your README
Markdown
[](/listings/toolprint--hypertool-mcp)HTML
<a href="/listings/toolprint--hypertool-mcp"><img src="/api/listings/toolprint--hypertool-mcp/badge.svg" alt="findsafeskills safety rating" /></a>Install
Install instructions from the README
As written by the repo's author. findsafeskills has not verified these steps.
Step 1: Copy Your Existing Config
# In your project directory cp .mcp.json .mcp.hypertool.json
Step 2: Point Your AI to HyperTool
Replace your `.mcp.json` with:
{
"mcpServers": {
"hypertool": {
"command": "npx",
"args": ["-y", "@toolprint/hypertool-mcp", "mcp", "run", "--mcp-config", ".mcp.hypertool.json"]
}
}
}Step 3: Create Your First Toolset
Restart your AI and try:
You: "Create a toolset called 'coding' with git and docker tools" AI: "Created 'coding' toolset with 15 focused tools" You: "Switch to coding toolset" AI: "Equipped! I now have just the tools needed for development"
**That's it!** Your AI is now focused and effective. ๐
๐ก **Want automated setup?** Try our interactive `setup` command - see [Advanced Guide](guides/ADVANCED.md#setup-command) for details.
๐ **Configuration Mode:** HyperTool uses a smart Configuration Mode to keep toolset management separate from your operational tools. Learn more in the [Configuration Mode Guide](guides/CONFIGURATION_MODE.md).
What was scanned
The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.
README.md ยท README ยท 419 lines
View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)
- <picture>
- <source media="(prefers-color-scheme: dark)" srcset="./assets/hypertool_darkmode_wordmark_horizontal.png">
- <source media="(prefers-color-scheme: light)" srcset="./assets/hypertool_lightmode_wordmark_horizontal.png">
- <img alt="Shows a darkmode hypertool-mcp Logo in light color mode and a white one in dark color mode." src="./assets/hypertool_lightmode_wordmark_horizontal.png" width="full">
- </picture>
- <h1 align="center">Give your AI the best tools from all your MCPs ๐ฏ</h1>
- [](https://npmjs.com/package/@toolprint/hypertool-mcp)
- [](https://npmjs.com/package/@toolprint/hypertool-mcp)
- [](https://discord.gg/MbvndnJ45W)
- [](https://www.typescriptlang.org/)
- [](https://modelcontextprotocol.io)
- [](LICENSE)
- ## โก Features
- ### ๐ **Break Free from Tool Limits**
- Connect unlimited MCP servers. Use 10, 50, or 500+ tools total - your AI only sees what it needs.
- ### ๐ฏ **Task-Specific Toolsets**
- Build "git-essentials" with 5 tools instead of drowning in 47 Git commands. Switch contexts instantly.
- ### ๐ง **Smart Tool Descriptions**
- Enhance tools with examples and context. Watch your AI pick the right tool 89% more often.
- ## ๐ Quick Start
- ### Step 1: Copy Your Existing Config
- ```bash
- # In your project directory
- cp .mcp.json .mcp.hypertool.json
- ```
- ### Step 2: Point Your AI to HyperTool
- Replace your `.mcp.json` with:
- ```json
- {
- "mcpServers": {
- "hypertool": {
- "command": "npx",
- "args": ["-y", "@toolprint/hypertool-mcp", "mcp", "run", "--mcp-config", ".mcp.hypertool.json"]
- }
- }
- }
- ```
- ### Step 3: Create Your First Toolset
- Restart your AI and try:
- ```
- You: "Create a toolset called 'coding' with git and docker tools"
- AI: "Created 'coding' toolset with 15 focused tools"
- You: "Switch to coding toolset"
- AI: "Equipped! I now have just the tools needed for development"
- ```
- **That's it!** Your AI is now focused and effective. ๐
- ๐ก **Want automated setup?** Try our interactive `setup` command - see [Advanced Guide](guides/ADVANCED.md#setup-command) for details.
- ๐ **Configuration Mode:** HyperTool uses a smart Configuration Mode to keep toolset management separate from your operational tools. Learn more in the [Configuration Mode Guide](guides/CONFIGURATION_MODE.md).
- ## ๐ญ Personas: Pre-configured Tool Bundles (NEW!)
- Don't want to configure from scratch? Use personas - ready-to-use MCP server bundles with pre-built toolsets.
- ### What are Personas?
- Think of personas as "app bundles" for your AI - they come with:
- - โ Pre-configured MCP servers
- - โ Curated toolsets for specific workflows
- - โ Everything you need to get started instantly
- ### Quick Start with Personas
- ```bash
- # 1. Clone the persona collection
- git clone https://github.com/toolprint/awesome-mcp-personas
- # 2. Add a persona (e.g., web-dev persona)
- hypertool-mcp persona add awesome-mcp-personas/personas/web-dev
- # 3. Run with the persona
- npx -y @toolprint/hypertool-mcp mcp run --persona web-dev
- ```
- That's it! No server configuration needed. The persona brings its own servers and toolsets.
- ๐ฆ **Browse all available personas**: [awesome-mcp-personas](https://github.com/toolprint/awesome-mcp-personas)
- ### Available Personas
- | Persona | Included Servers | Best For |
- |---------|-----------------|----------|
- | **web-dev** | Git, Docker, Filesystem, Browser, Testing | Full-stack web development |
- | **data-scientist** | Python, Jupyter, Database, Filesystem, Plotting | Data analysis & ML workflows |
- | **devops** | Docker, Kubernetes, AWS, Terraform, Monitoring | Infrastructure & deployment |
- | **content-creator** | Notion, Slack, Grammar, SEO, Social | Writing & content management |
- | **researcher** | Perplexity, Arxiv, Wikipedia, Filesystem | Research & knowledge work |
- ### Persona vs Standard Mode
- ```bash
- # Standard Mode (use your existing MCP servers):
- npx -y @toolprint/hypertool-mcp mcp run --mcp-config .mcp.hypertool.json
- # Persona Mode (bundled servers + pre-built toolsets):
- npx -y @toolprint/hypertool-mcp mcp run --persona web-dev
- # Persona Mode with specific toolset:
- npx -y @toolprint/hypertool-mcp mcp run --persona web-dev --equip-toolset frontend
- ```
- ๐ก **Pro tip**: Personas can be mixed with your existing servers! Add `--mcp-config` to include your custom servers alongside the persona's servers.
- ๐ **Learn more**: See the complete [Personas Guide](guides/PERSONAS.md) for detailed instructions, creating custom personas, and troubleshooting.
- ## ๐ Context Measurement (NEW!)
- See exactly how much context each tool consumes. Optimize your toolsets with token estimates for every tool.
- <div align="center">
- <img src="./assets/toolset_context.png" alt="Toolset Context View" width="700">
- <p><em>Active toolset showing token usage per tool</em></p>
- </div>
- **Why it matters:**
- - ๐ฏ **Optimize context usage** - Identify heavyweight tools consuming your context window
- - ๐ **Make informed decisions** - See token costs before adding tools to toolsets
- - ๐ **Compare alternatives** - Find lighter tools that do the same job
- - ๐ก **Budget your context** - Understand exactly what you're exposing to your AI
- **How to use:**
- Ask your AI to use these MCP tools to see context information:
- - `list-available-tools` - Shows token estimates for all available tools
- - `get-active-toolset` - Shows token usage for your currently equipped toolset
- Each tool displays estimated tokens and percentage of total context consumed. Perfect for building lean, efficient toolsets!
- ## ๐ฌ Demo
- ### Hotswap toolsets across 100+ tools
- _Targeted toolsets across any number of MCPs. Swap to the best toolset for a goal with a tool call. Dynamic tool registration._
- <div align="center">
- <a href="https://www.youtube.com/watch?v=43fkKOBayCg">
- <img src="./demos/build_dynamic_toolsets_1080p_25fps.gif" alt="HyperTool Demo - Click for full video" width="800">
- </a>
- </div>
- ## ๐๏ธ How It Works
- ```
- Before: Tool Chaos ๐ต
- โโโโโโโโโโโโโโโ โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
- โ Claude/ โโโโถโ 50+ tools from 8 servers โ
- โ Cursor โ โ โ Wrong picks โ
- โ โ โ โ Slow decisions โ
- โ โ โ โ Confused context โ
- โโโโโโโโโโโโโโโ โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
- After: Expert Mode ๐ฏ
- โโโโโโโโโโโโโโโ โโโโโโโโโโโโโโโโ โโโโโโโโโโโโโโโโโโโ
- โ Claude/ โโโโถโ HyperTool โโโโถโ ALL Your Tools โ
- โ Cursor โ โ (Local) โ โ (Same servers) โ
- โโโโโโโโโโโโโโโ โโโโโโโโโโโโโโโโ โโโโโโโโโโโโโโโโโโโ
- โ
- โผ
- โโโโโโโโโโโโโโโโโโโ
- โ Smart Toolsets โ
- โ ๐จ coding (5) โ โ "I'm coding now"
- โ ๐ writing (3) โ โ "I'm writing now"
- โ ๐ analysis (4) โ โ "I'm analyzing now"
- โโโโโโโโโโโโโโโโโโโ
- โ Expert picks every time
- ```
- ### What's a "Toolset"? Think Playlists for Your AI
- Just like Spotify playlists organize your music, toolsets organize your AI tools:
- ```
- ALL YOUR TOOLS (64 total) YOUR TOOLSETS
- โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ โโโโโโโโโโโโโโโโโโโโ
- โ ๐ณ Docker (19 tools) โ โ ๐จ "coding" โ
- โ โข build_image โ โโโโโถ โ โข git.status โ
- โ โข create_container โ โ โ โข git.commit โ
- โ โข run_container โ โ โ โข docker.build โ
- โ โข stop_container โ โ โ โข docker.run โ
- โ โข [... 15 more] โ โ โ โข github.pr โ
- โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโค โ โโโโโโโโโโโโโโโโโโโโ
- โ ๐ Git (12 tools) โโโโโค
- โ โข status โ โ โโโโโโโโโโโโโโโโโโโโ
- โ โข commit โ โ โ ๐ "writing" โ
- โ โข push โ โโโโโถ โ โข notion.create โ
- โ โข [... 9 more] โ โ โข slack.send โ
- โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโค โ โข grammarly.fix โ
- โ ๐ Notion (8 tools) โโโโโโโ โโโโโโโโโโโโโโโโโโโโ
- โ ๐ฌ Slack (6 tools) โ โ
- โ ๐ Linear (10 tools) โ โ โโโโโโโโโโโโโโโโโโโโ
- โ ๐งช Testing (9 tools) โ โโโถ โ ๐ "debugging" โ
- โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ โ โข logs.search โ
- โ โข docker.logs โ
- AI sees ALL 64 tools = confused ๐ต โ โข traces.view โ
- โโโโโโโโโโโโโโโโโโโโ
- AI sees 3-5 tools = focused ๐ฏ
- ```
- ## ๐ผ Real-World Toolsets
- Create focused toolsets for different workflows:
- ### ๐จ Development Mode
- ```
- "deep-coding": git + docker + filesystem (12 tools)
- โ Everything you need for feature development
- "code-review": git + github + linear (10 tools)
- โ Review PRs, update tickets, merge with confidence
- "debugging": logs + docker + traces + alerts (8 tools)
- โ Find and fix issues fast
- ```
- ### ๐ Content Creation
- ```
- "writing": notion + grammarly + slack (6 tools)
- โ Blog posts, docs, and team updates
- "research": perplexity + notion + filesystem (7 tools)
- โ Deep dives with organized notes
- ```
- ### ๐ฌ Real Chat Example
- ```
- You: "I need to debug our API"
- AI: "I'll switch to the debugging toolset for better focus"
- [Now has: logs, traces, curl, docker]
- You: "Actually, let's write the incident report"
- AI: "Switching to writing toolset"
- [Now has: notion, slack, templates]
- ```
- ๐ก **Pro tip**: Start with 3-5 tools per toolset. Your AI will thank you!
- ## ๐ All Features
- Explore everything HyperTool can do:
- | Feature | Description | Guide |
- |---------|-------------|-------|
- | **๐ญ Personas** | Pre-configured MCP server bundles with curated toolsets. Get started instantly with ready-to-use workflows for web-dev, data science, DevOps, and more. | [Personas Guide](guides/PERSONAS.md) |
- | **๐ Server Groups** | Organize MCP servers into logical groups. Launch related servers together, switch between projects, and maintain focused contexts. | [Advanced Guide](guides/ADVANCED.md) |
- | **๐ Context Measurement** | See token estimates for every tool. Optimize your toolsets by understanding exactly how much context each tool consumes. | [Context Measurement](docs/features/context-measurement.md) |
- | **๐ง Configuration Mode** | Smart separation of toolset management from operational tools. Keep your AI focused on work, not configuration. | [Configuration Mode Guide](guides/CONFIGURATION_MODE.md) |
- | **๐ฏ Dynamic Toolsets** | Build, modify, and switch between toolsets on the fly. Adapt your AI's capabilities to match your current task. | [Examples & Recipes](guides/EXAMPLES.md) |
- | **๐ง Tool Annotations** | Enhance tools with custom descriptions, examples, and context. Improve your AI's tool selection accuracy by 89%. | [Advanced Guide](guides/ADVANCED.md) |
- | **๐ HTTP Mode** | Run HyperTool as a long-lived HTTP server for persistent connections and faster response times. | [Advanced Guide](guides/ADVANCED.md) |
- | **๐ Unlimited Servers** | Connect as many MCP servers as you need. Break free from the 100-tool limit without sacrificing performance. | [Quick Start](#-quick-start) |
- ## โ FAQ
- ### General Questions
- **Q: How is this different from just using MCP servers directly?**
- A: HyperTool lets you use unlimited MCP servers without hitting the 100-tool limit, and dynamically switches between focused toolsets for better AI performance.
- **Q: What's the difference between Personas and Standard Mode?**
- A: Standard Mode uses your existing MCP server configurations. Personas are pre-packaged bundles that include both MCP servers AND curated toolsets - perfect for getting started quickly or trying new workflows.
- **Q: Can I use multiple toolsets at once?**
- A: In stdio mode (default), use `--equip-toolset <name>` when launching. HTTP mode supports one active toolset but you can switch anytime.
- **Q: Where are my toolsets and configurations stored?**
- A: Everything is stored locally in `~/.toolprint/hypertool-mcp/`:
- - Personas: `~/.toolprint/hypertool-mcp/personas/`
- - Toolsets: `~/.toolprint/hypertool-mcp/toolsets/`
- - Preferences: `~/.toolprint/hypertool-mcp/config/`
- You can directly edit these files when HyperTool is not running.
- ### Setup & Compatibility
- **Q: Does this work with Claude Desktop / Cursor / Claude Code?**
- A: Yes! Cursor has full hot-swapping support. Claude Desktop works with restart. Claude Code [hot-swap coming soon](https://github.com/anthropics/claude-code/issues/411).
- **Q: What if an MCP server goes down?**
- A: HyperTool monitors health and automatically reconnects when servers come back. Your toolsets stay intact.
- **Q: Can I share toolsets with my team?**
- A: Import/export is coming soon! For now, you can copy and share toolset files - they'll work if your team has the same MCP servers configured.
- **Q: How accurate are the token estimates in context measurement?**
- A: The estimates use BPE-based approximation for consistent relative comparisons between tools. They're perfect for understanding which tools consume more context, but not exact counts since different LLMs use different tokenizers.
- **Q: Does context measurement slow down my toolsets?**
- A: No! Token counts are cached and add less than 10ms overhead. You won't notice any performance impact.
- ### Technical Questions
- **Q: How do I add tools from a new MCP server?**
- A: Just add the server to your `.mcp.hypertool.json` config. It's automatically available for toolsets.
- **Q: Can I use this in production?**
- A: Yes! For enterprise support, [contact us](mailto:support@onegrep.dev?subject=HyperTool%20Production%20Use&body=Hi%20team%2C%0A%0AI'm%20interested%20in%20using%20HyperTool%20in%20production.%0A%0ACompany%3A%20%0AUse%20case%3A%20%0AScale%3A%20%0A%0AThanks!).
- ## ๐ฎ App Compatibility
- **Works with ANY MCP-compatible app!** HyperTool is a standard MCP server, so if your app supports MCP, it supports HyperTool.
- ### Hot-swap Toolsets Without Restarts
- | App | Status | How to Switch Toolsets |
- |-----|---------|------------------------|
- | **Cursor/VSCode** | โ Full support | Switch toolsets instantly - no restart needed! |
- | **Claude Code** | โณ Coming soon | Use `--equip-toolset <name>` flag ([track progress](https://github.com/anthropics/claude-code/issues/4118)) |
- | **Claude Desktop** | โณ In progress | Restart app after switching toolsets |
- ---
- ๐ **Learn More**
- - ๐ญ [Personas Guide](guides/PERSONAS.md) - Complete guide to using and creating personas
- - ๐ฌ [Research & Performance](guides/RESEARCH.md) - Why focused toolsets work
- - ๐ [Advanced Features](guides/ADVANCED.md) - Tool annotations, HTTP mode, CLI
- - ๐ง [Troubleshooting](guides/TROUBLESHOOTING.md) - Common issues and solutions
- - ๐ [Examples & Recipes](guides/EXAMPLES.md) - Toolset patterns for every workflow
- ## ๐ ๏ธ Development Setup
- ### Prerequisites
- - Node.js 18+
- - Python 3.8+ (for pre-commit hooks)
- ### Quick Setup
- ```bash
- # Clone and install
- git clone https://github.com/toolprint/hypertool-mcp.git
- cd hypertool-mcp
- just setup-dev # Installs dependencies and pre-commit hooks
- ```
- ### Pre-commit Hooks
- This project uses pre-commit hooks to ensure code quality:
- ```bash
- # Install pre-commit hooks (included in setup-dev)
- just setup-pre-commit
- # Run hooks manually
- just pre-commit-check # On staged files
- just pre-commit-check-all # On all files
- # Skip hooks for emergency commits (use sparingly)
- SKIP=eslint,typescript git commit -m "emergency fix"
- ```
- ### Available Commands
- ```bash
- just build # Build the project
- just test # Run tests
- just lint # Run linting
- just format # Format code
- just typecheck # Check types
- just pre-publish-checks # Run all quality checks
- ```
- ### Service command
- The `hypertool-mcp service` subcommand is currently disabled and will exit with a
- notification when invoked.
- ## ๐ค Contributing
- Found a bug? Have an idea? We'd love your help!
- - ๐ [Report issues](https://github.com/toolprint/hypertool-mcp/issues)
- - ๐ก [Share ideas](https://github.com/toolprint/hypertool-mcp/discussions)
- - ๐ง [Submit PRs](https://github.com/toolprint/hypertool-mcp/pulls)
- ## ๐ License
- MIT License - see [LICENSE](LICENSE) file for details.
- ---
- <div align="center">
- **Built by developers who got tired of watching AI pick the wrong tools** ๐ฏ
- <a href="https://toolprint.ai">
- <img src="./assets/toolprint.png" alt="Toolprint" width="200">
- </a>
- <p>
- <strong>Built with โค๏ธ by <a href="https://toolprint.ai">Toolprint</a></strong><br>
- <sub>ยฉ 2025 OneGrep, Inc.</sub>
- </p>
- </div>
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If itโs helped, pass it on.