183 lines
9.0 KiB
Markdown
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.
|
|
|
|

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