The Problem
Each MCP server consumes 3K-30K tokens per request. Connect 5 servers and you've burned 55K tokens before the conversation starts. Connect 10+ and you're at 100K tokens.
The math is brutal: Claude Opus 4.5 at $5/M input tokens, 20 days × 10 conversations × 10 messages × 3K tokens = $30/month per MCP server - even if you never use the tools.
And then there's context rot - your AI literally gets dumber as you add more tools (Chroma Research, 2025).
The Solution
OneTool is one MCP server that exposes tools as a Python API. Instead of reading tool definitions, your agent writes code:
__run brave.search(query="react docs 2026")
Configure one MCP server. Use unlimited tools.
"Agents scale better by writing code to call tools instead. This reduces the token usage from 150,000 tokens to 2,000 tokens...a cost saving of 98.7%"
96% fewer tokens. 30× lower cost. No context rot.
Install
Requires uv:
uv tool install 'onetool-mcp[all]' # everything
onetool init --config ~/.onetool
Add to Claude Code:
claude mcp add onetool -- onetool serve --config ~/.onetool/onetool.yaml --secrets ~/.onetool/secrets.yaml
Or manually add to ~/.claude/mcp.json:
{
"mcpServers": {
"onetool": {
"command": "onetool",
"args": ["serve", "--config", "/Users/yourname/.onetool/onetool.yaml", "--secrets", "/Users/yourname/.onetool/secrets.yaml"]
}
}
}
That's it. All 100+ tools work out of the box.
Verify: onetool init validate --config ~/.onetool/onetool.yaml
Use from the CLI
Works as an MCP server and as a direct CLI bridge into a running MCP process. Useful for agent harnesses, scripts, and automation:
# Recommended local MCP root mode: stdio
onetool serve --config .onetool/onetool.yaml
# URL-based MCP root mode for containerized clients
onetool serve --transport http --config .onetool/onetool.yaml --host 127.0.0.1 --port 8767 --path /mcp
# Enable the MCP-owned direct API in onetool.yaml:
# direct.host.enabled: true
# Start OneTool as MCP, then use the port printed in startup logs.
onetool direct run --port 8765 "ot.packs()" --format json | jq '.[0].name'
onetool direct run --port 8765 "brave.search(query='latest AI news')" --format raw
Features
| Feature | Description |
|---|---|
| 96% Token Savings | ~2K tokens no matter how many tools you add |
| 100+ Built-in Tools | Web search, databases, file ops, diagrams, conversions |
| Explicit Execution | See exactly what runs — __run brave.search(q="AI") |
| Live Whiteboard | Draw diagrams with a Mermaid-compatible DSL via Excalidraw |
| MCP Server Proxy | Wrap existing MCP servers without the tool tax |
| Encrypted Secrets | age-encrypted secrets.yaml backed by your OS keychain |
| Forge Tools | Build new tools as part of the conversation |
| Image Vision | Routes to a cheaper, better vision model via ot_image (img). Zero host tokens. Supports local files, URLs, clipboard; PNG, JPEG, GIF, WebP, TIFF, HEIC, AVIF, SVG. |
| Smart Context | ot_context (ctx) — SQLite+FTS5 store. Search and navigate large outputs without filling the context window. |
| Caveman Compact | ot_caveman (cm) — LLM-powered text compaction. 55–65% on tech prose, 25–31% on search results, 45–55% on conversational prose. __compact__ = True applies it to any tool call. Code blocks, URLs, and security warnings are never modified. |
| Smart Tools | Delegate to cheaper LLMs (10× savings) |
| Security Layers | AST validation, path boundaries, output sanitisation |
Tools
27+ packs, 230+ tools ready to use:
| Pack | Tools | Extra | Description |
|---|---|---|---|
brave | search, news | [util] | Web and news search |
chrome_util | highlight_element, guide_user | [dev] | Browser annotations (DevTools) |
context7 | search, doc | [dev] | Library documentation |
convert | pdf_to_md, docx_to_md, pptx_to_md | [util] | Document conversion |
db | query, schema, tables, sample | [dev] | Database operations |
diagram | create, get_playground_url | [dev] | Mermaid / Kroki diagrams |
excel | read, write, query | [util] | Excel files |
file | read, write, grep, slice, toc | [util] | File operations |
ground | search | [util] | Google Grounding search |
knowledge | search, ask, write, read, grep | [util] | RAG knowledge base (FTS5+vector) |
mem | write, read, search, grep, ask, inspect, query | [util] | Persistent memory |
ot_forge | create_ext, validate_ext, install_skills | Scaffold new tool packs | |
ot_context (ctx) | write, read, search, grep, slice, toc | Smart context store (SQLite+FTS5) | |
ot_caveman (cm) | compact, expand, input | LLM-powered text compaction and expansion | |
ot_image (img) | load, load_batch, ask, summary, list, delete, purge | [util] | Image vision via dedicated model |
ot_llm | transform, transform_file | LLM-powered transforms | |
ot_secrets | init, encrypt, audit, rotate | Secrets encryption | |
ot_timer | start, elapsed, list | Named timers | |
ot | help, tools, stats, skills | Introspection | |
package | npm, pypi, cargo | [dev] | Package versions |
play_util | highlight_element, guide_user | [dev] | Browser annotations (Playwright) |
ripgrep | search, count | [dev] | Fast code search |
tavily | search, search_batch, research | [util] | AI-native search |
webfetch | fetch, fetch_batch | [dev] | Web fetching |
whiteboard | open, draw, screenshot, save | [dev] | Live Excalidraw canvas |
📖 Complete tools reference — full summary table with all 230+ tools
MCP Server Proxy
Wrap any existing MCP server and call it explicitly - simple yaml config without the tool tax:
# .onetool/onetool.yaml
servers:
local_tools:
type: stdio
command: npx
args: ["-y", "some-mcp-server@latest"]
private_api:
type: http
url: ${PRIVATE_MCP_URL}
auth:
type: bearer
token: ${PRIVATE_MCP_TOKEN}
__run private_api.read_resource(path="README.md")
Extending
Drop a Python file, get a pack. No registration, no config:
# .onetool/tools/wiki.py
pack = "wiki"
def summary(*, title: str) -> str:
"""Get Wikipedia article summary."""
import httpx
url = f"https://en.wikipedia.org/api/rest_v1/page/summary/{title}"
return httpx.get(url).json().get("extract", "Not found")
__run wiki.summary(title="Python_(programming_language)")
Documentation
- Quickstart - 30 seconds to first tool call
- Installation - All platforms
- Configuration - YAML schema
- Tools Reference - All 100+ tools
- Security - Security layers
- Extending - Build your own
- Dev Docs - Internal developer documentation
- Specifications - OpenSpec specifications index
References
- Code Execution with MCP - Anthropic Engineering
- Context Rot - Chroma Research
Telemetry
OneTool sends anonymous startup pings (event type, version, OS). No personal data. Opt out: export DO_NOT_TRACK=1 or set telemetry.enabled: false in onetool.yaml. Details
Issues
Check for existing issues first:
- Browse the tracker: github.com/beycom/onetool-mcp/issues
- Search with GitHub syntax:
is:issue repo:beycom/onetool-mcp <keyword>
Raise a new issue: github.com/beycom/onetool-mcp/issues/new
Support
If you find OneTool useful:
License
GPLv3