onetool-mcp

🧿 One MCP for developers - no tool tax, no context rot.250+ tools your agent calls as Python code: search, docs, files, databases, diagrams, vision, memory - plus a proxy for every MCP server you already use.

Works with Claude Code, Cursor, Codex - any MCP client

The Problem

Every MCP server re-sends its tool definitions on every request: 3K-30K tokens each. Connect 5 servers and you've burned 55K tokens before the conversation starts. Connect 10+ and you're at 100K.

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:

__onetool brave.search(query="react 19 server components")

Configure one MCP server. Use unlimited tools - ~2K tokens no matter how many you add.

> "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%"

>

> — Anthropic Engineering

97% fewer tokens. 30× lower cost. No context rot. (Measured - 47,660 → 1,131 input tokens against 18 MCP servers.)

📖 Read the full story

Code Is the Interface

Because tools are Python functions, your agent does things tool-call JSON can't: batch, chain, loop, compose.

__onetool
page = webfetch.fetch(url="https://fastmcp.dev/changelog", output_format="markdown")
notes = ot_llm.transform(data=page, prompt="Summarise the breaking changes")
mem.write(topic="deps/fastmcp", content=notes)

Three packs, one request. Intermediate results flow between tools as variables - the page body never touches your context window, and the summarising runs on a cheap model instead of your expensive coding agent.

Every call is explicit and reviewable - `__onetool brave.search(query="...")` shows you exactly what runs. No tool-selection guessing.

And the runtime is built for how agents actually type:

• `mem.search(q="auth")` works - any unambiguous parameter prefix resolves (`q=` → `query=`)
• `wb.draw(...)` works - packs have short aliases (`wb`, `ctx`, `img`)
• `github.listRepositories()` works on proxied servers - snake/camel/Pascal all resolve
• A typo'd tool gets a did-you-mean, a disconnected server names the command that fixes it
• Oversized results come back as a searchable handle instead of flooding the window

Install

Bootstrap (installs `uv` if missing, installs OneTool, initialises config, prints MCP config):

curl -LsSf https://onetool.beycom.online/install.sh | sh          # macOS / Linux
irm https://onetool.beycom.online/install.ps1 | iex               # Windows (PowerShell)

Or install manually with uv:

uv tool install 'onetool-mcp[all]'   # everything
onetool init --config ~/.onetool

Then print ready-to-paste MCP client config with resolved absolute paths and add it

to your client (`claude-code`, `claude-desktop`, `cursor`, or `vscode`):

onetool init mcp-config --client claude-code   # or omit --client for all four

That's it. All 250+ tools work out of the box.

Verify: `onetool init validate --config ~/.onetool/onetool.yaml`

Install the `ot-ref` skill into your agent with vercel-labs/skills - it teaches the call conventions and ships a greppable index of every tool signature:

npx skills add https://github.com/beycom/onetool-mcp --skill ot-ref --agent claude

📖 Full installation guide

What's Inside

Tools

28 packs, 253 tools ready to use (`console` in beta):

📖 Complete tools reference — every signature, generated from source

MCP Server Proxy

Keep the MCP servers you already use. Wrap them in YAML and call them explicitly - as Python namespaces, without their 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}

__onetool private_api.read_resource(path="README.md")

Proxied servers can be enabled, disabled, and restarted mid-conversation with `ot_servers` - no client restart.

📖 Configuration guide

Secrets You Can Commit

`onetool init` walks you through encrypted secrets: values in `secrets.yaml` are age-encrypted, the private key lives in your OS keychain, and decryption happens transparently at load.

# secrets.yaml - safe to inspect, safe to commit
brave_api_key: age1enc:YWdlLWVuY3J5cHRpb24ub3JnL3YxCi0+IFgyNT...

📖 Security guide

Use from the CLI

Works as an MCP server and as a direct CLI bridge into the same running process - loaded config, secrets, and proxy connections stay warm. 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

📖 Direct usage guide

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")

__onetool wiki.summary(title="Python_(programming_language)")

📖 Creating tools guide

Documentation

• Quickstart - 30 seconds to first tool call
• Installation - All platforms
• Configuration - YAML schema
• Tools Reference - All 253 tools
• Security - The layered security model
• 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 `

Raise a new issue: github.com/beycom/onetool-mcp/issues/new

Support

If you find OneTool useful:

License

GPLv3