toolgate/README.md

183 lines
9.0 KiB
Markdown

# toolgate
One key for 27 agent tools. 18 are free. Every call is priced in micro-USD before it runs and billed only if it succeeds.
![toolgate: list the free tools, call Wikipedia, geocode an address](docs/demo.gif)
This repo is the open-source command line, the Claude Code skill and the MCP config for
[Scribase Toolgate](https://toolgate.scribase.com). The hosted service does the work; this is how you
reach it from a terminal, a script or a coding agent. MIT licensed, no dependencies, Node 18+.
## Try it in 10 seconds (no key, no card)
```bash
npx github:caelum0x/toolgate tools --free
```
Output on 2026-11-12:
```
tool does effect price
company.lei.lookup Legal entity identifier (LEI) read free
company.sec.filings Company SEC filings read free
dev.github.repos.search Search code repositories read free
dev.package.info.registries Package registry info read free
domain.dns.lookup DNS lookup read free
domain.rdap.whois Domain registration (RDAP/WHOIS) read free
geo.geocode.nominatim Geocode an address or place read free
geo.geocode.photon Geocode an address or place read free
knowledge.wikipedia.summary Look up a topic summary read free
menivor.video.status Video job status read free
relay.chat.complete LLM chat completion read free
research.papers.arxiv Search research papers read free
research.papers.openalex Search research papers read free
social.hn.search Search Hacker News read free
weather.forecast.open-meteo Weather forecast read free
web.read.readable Read a web page as markdown read free
web.search.brave Search the web read free
web.search.searxng Search the web read free
27 tools, 18 free. Prices in micro-USD (1,000,000 µ$ = $1), charged only when a call succeeds.
```
## Get a key and call a tool
```bash
npx github:caelum0x/toolgate signup --org "my-team"
```
```
org created my-team-hxifk9
key (shown once) sk-t0-...
saved to ~/.config/toolgate/config.json (mode 600). Or export TOOLGATE_KEY=...
Free tools work now. Paid tools answer 402 with a top-up link until a balance is attached.
Connect Claude Code:
claude mcp add --transport http toolgate https://toolgate.scribase.com/mcp --header "Authorization: Bearer sk-t0-..."
```
No email, no card, no human in the loop: the key comes back in the same response. Then:
```bash
npx github:caelum0x/toolgate call knowledge.wikipedia.summary title="Ada Lovelace"
```
```
{
"summary": "Augusta Ada King, Countess of Lovelace, also known as Ada Lovelace, was an English mathematician and writer chiefly known for work on Charles Babbage's proposed mechanical general-purpose computer, the analytical engine. ...",
"thumbnail": "https://thumb.wikimedia.org/wikipedia/commons/thumb/4/4c/Ada_Lovelace_daguerreotype_by_Antoine_Claudet_1843_-_cropped.png/330px-Ada_Lovelace_daguerreotype_by_Antoine_Claudet_1843_-_cropped.png?utm_source=en.wikipedia.org&utm_campaign=api&utm_content=thumbnail",
"title": "Ada Lovelace",
"url": "https://en.wikipedia.org/wiki/Ada_Lovelace"
}
provider=wikipedia cost=free cache=miss call=call_01m77syn3y59mvjbfaq8t89wjr
```
Data goes to stdout as JSON, the provider and cost line goes to stderr, so `| jq` works.
If `npx github:...` is slow for you, clone and run `node bin/toolgate.mjs` or `npm link` once to get a
`toolgate` command.
## Connect Claude Code (or any MCP client)
The MCP endpoint is `https://toolgate.scribase.com/mcp` (streamable HTTP, bearer key). Copy the line
`signup` printed, or print it again with `toolgate mcp`:
```bash
claude mcp add --transport http toolgate https://toolgate.scribase.com/mcp --header "Authorization: Bearer sk-t0-..."
```
Checked 2026-11-12: `claude mcp list` then shows `toolgate: https://toolgate.scribase.com/mcp (HTTP) - ✔ Connected`.
The server exposes five MCP tools: `search_tools`, `describe_tool`, `call_tool`, `balance`, `usage`.
As a Claude Code plugin (adds the MCP server plus the skill in `skills/toolgate/SKILL.md`):
```bash
export TOOLGATE_KEY=sk-t0-... # from signup
claude plugin marketplace add caelum0x/toolgate
claude plugin install toolgate@toolgate
```
Skill only, for any agent that reads `SKILL.md` (Cursor, Codex, Gemini CLI, ...):
```bash
npx skills add caelum0x/toolgate
```
Cursor or a hand-written config: `toolgate mcp --client cursor` prints the JSON with your saved key.
The repo's [`.mcp.json`](.mcp.json) reads the key from `TOOLGATE_KEY`.
## Free tools, checked live
All 18 tools above are priced at 0 µ$. On 2026-11-12 I called each one with a fresh key:
- 13 answered with real data: `domain.dns.lookup`, `domain.rdap.whois`, `geo.geocode.nominatim`,
`geo.geocode.photon`, `weather.forecast.open-meteo`, `dev.package.info.registries`,
`dev.github.repos.search`, `company.sec.filings`, `company.lei.lookup`, `research.papers.arxiv`,
`research.papers.openalex`, `social.hn.search`, `web.read.readable`, `knowledge.wikipedia.summary`
(that is 14 with Wikipedia).
- `web.search.brave` is free to route but needs your own Brave key stored on Toolgate (`no_provider` otherwise).
- `menivor.video.status` needs a Menivor connection.
- `web.search.searxng` and `relay.chat.complete` returned upstream errors that day (public SearXNG
instance down; Relay rejected the catalog's example model name). They cost nothing when they fail.
## Pricing, in plain words
- Prices are in micro-USD. 1,000,000 µ$ = $1. `200 µ$` is $0.0002.
- Free tools: $0, no balance needed, a fresh signup can call them right away.
- Paid tools today: `scribase.db.query` 50 µ$, `rally.email.verify` 200 µ$, `rally.email.send` 400 µ$ per
recipient, `scribase.auth.magic_link.send` 400 µ$, `rally.leads.search` 2000 µ$ per result,
`rally.company.enrich` 5000 µ$, `scribase.db.branch.create` $0.01, `menivor.*` video tools up to $0.02.
`toolgate tools` always shows the live numbers.
- Before a paid call runs, the price is quoted and held. If the call fails, the hold is released and
nothing is charged. If it succeeds, exactly the quoted amount is captured.
- A fresh signup has no balance: paid calls return `402 insufficient_balance` with a `topup_url`.
Top-ups go through the hosted checkout; no card is needed to use the free tools.
- `--max-cost N` refuses anything quoted above N µ$. Projects can also set daily and monthly caps.
## CLI reference
```
toolgate tools [--free] [--json] every tool with its price (no key needed)
toolgate signup [--org NAME] [--email E] create an org and a key (free, no card)
toolgate search <what you want to do> tools for a task, with prices
toolgate describe <tool-id> input fields, example, price
toolgate call <tool-id> key=value ... run it; data on stdout, cost on stderr
toolgate call <tool-id> --input '{...}' same, JSON input
toolgate balance balance, caps, top-up link
toolgate usage [--group tool|day] calls and spend
toolgate mcp [--client claude|cursor|json] connection snippet for your editor
```
`key=value` values are coerced: `limit=1` is a number, `strict=true` a boolean, anything starting with
`{`, `[` or `"` is parsed as JSON. Exit codes: 0 ok, 1 error, 2 unknown command, 3 insufficient balance.
Config: `TOOLGATE_KEY` and `TOOLGATE_URL` env vars win over `~/.config/toolgate/config.json`.
`NO_COLOR=1` turns colours off.
## What is in this repo
- `bin/toolgate.mjs`, `src/`: the CLI. Plain Node, no packages, about 400 lines.
- `skills/toolgate/SKILL.md`: the agent skill (when to use which tool, how to read prices, the rules).
- `.mcp.json`, `.claude-plugin/`, `.cursor-plugin/`: the MCP and plugin manifests.
- `demo/demo.tape`: the [vhs](https://github.com/charmbracelet/vhs) script that recorded the GIF above
against the live service.
The Toolgate server itself is Rust and lives in
[caelum0x/railyard/apps/toolgate](https://github.com/caelum0x/railyard/tree/main/apps/toolgate).
Docs: [toolgate.scribase.com/docs](https://toolgate.scribase.com/docs). Catalog with live prices:
[toolgate.scribase.com/catalog](https://toolgate.scribase.com/catalog). OpenAPI:
[/openapi.json](https://toolgate.scribase.com/openapi.json). Registry entry:
`com.scribase/toolgate` on the [official MCP registry](https://registry.modelcontextprotocol.io/v0/servers?search=toolgate).
## License
MIT.
## Ecosystem
Toolgate is part of the [Scribase](https://scribase.com) stack — one hosted backend instead of stitching Supabase + Neon + Clerk + Resend together.
- [Scribase](https://scribase.com) — hosted Postgres, Supabase/Neon alternative, free tier, no card required
- [Scribase Mail](https://mail.scribase.com) — Resend-compatible email API
- More open-source projects from this account: [git.ereboslab.com/caelum0x](https://git.ereboslab.com/caelum0x)