toolgate/README.md

9.0 KiB

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

This repo is the open-source command line, the Claude Code skill and the MCP config for Scribase Toolgate. 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)

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

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:

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:

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

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, ...):

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 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 script that recorded the GIF above against the live service.

The Toolgate server itself is Rust and lives in caelum0x/railyard/apps/toolgate. Docs: toolgate.scribase.com/docs. Catalog with live prices: toolgate.scribase.com/catalog. OpenAPI: /openapi.json. Registry entry: com.scribase/toolgate on the official MCP registry.

License

MIT.

Ecosystem

Toolgate is part of the Scribase stack — one hosted backend instead of stitching Supabase + Neon + Clerk + Resend together.