toolfare docs

For agents: connect your AI app

Pick the app you use. A chat app (Claude, ChatGPT) adds toolfare as a connector; an app with a terminal (Claude Code, Codex, Cursor) is given one sentence and sets itself up. Either way you approve the sign-in once in your browser, and every tool is quoted before a paid call.

https://api.toolfare.ai/mcp

Your own agent

• Point any MCP client at https://api.toolfare.ai/mcp. No pre-registration: the 401 carries an RFC 9728 pointer, and the client registers itself (RFC 7591) and runs authorization code with PKCE.
• A person approves the connection once in the browser; the grant can be revoked under Agents in the console.
• A client that speaks stdio only can bridge with mcp-remote. A server or CI job without a person to approve should use an API key instead.

API: call it from your code

One API key and one endpoint for every tool. Send HTTP from any language, or use the CLI from a shell; both reach the same endpoint and the same balance.

1. Create an API key

• Create one in the console under Agents → API keys. It is shown once.
• A key acts as you in your account. It needs a per-call and a daily spending limit, and it expires after 30, 90 or 365 days.
• Send it as Authorization: Bearer tf_live_…, or set TOOLFARE_API_KEY for the CLI.
• Paid calls on one key run one at a time. Use one key per worker for parallel jobs.
• Remove a key in the console; it stops on its next call.

2. Call it over HTTP

The endpoint is an MCP server, so any HTTP client can call it: POST a JSON-RPC tools/call with your API key. No initialize step or session is needed. Send Accept: application/json, text/event-stream (both are required); the reply is one server-sent event whose data: line is the JSON-RPC response.

curl -sS https://api.toolfare.ai/mcp \
  -H "Authorization: Bearer $TOOLFARE_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{
    "jsonrpc": "2.0", "id": 1, "method": "tools/call",
    "params": {
      "name": "call_capability",
      "arguments": {
        "tool_name": "ahrefs_site_metrics",
        "arguments": { "target": "linear.app", "date": "2026-10-26" },
        "max_cost": 40
      }
    }
  }'

event: message
data: {"jsonrpc":"2.0","id":1,"result":{"isError":false,"content":[{"type":"text","text":"{\"data\":{\"content\":\"…\"},\"billing\":{\"quoted_credits\":23,\"charged_credits\":23,\"charged_usd\":0.069,\"charge_reason\":\"charged\"},\"sources\":[]}"}]}}

The four calls

search_capabilities

{ query, limit?, offset? }Find tools by what you need, with each one’s price. Free.

describe_capability

{ tool_name }Full input schema, price model and estimate for one tool. Free.

call_capability

{ tool_name, arguments, max_cost, idempotency_key? }Run a tool. max_cost is in credits (40 = $0.12). The reply carries data, sources and billing.

get_balance

{}Credits left (1,000 credits = $3), billing mode and buy_credits_url. Free.

A refusal or a failed vendor call comes back as result.isError: true with the reason as text, for example “ahrefs_site_metrics is quoted at $0.069, above the max_cost of 5 ($0.015). Nothing was charged.”

Python

import json, os, requests

def toolfare(name, arguments):
    reply = requests.post(
        "https://api.toolfare.ai/mcp",
        headers={
            "Authorization": f"Bearer {os.environ['TOOLFARE_API_KEY']}",
            "Content-Type": "application/json",
            "Accept": "application/json, text/event-stream",
        },
        json={"jsonrpc": "2.0", "id": 1, "method": "tools/call",
              "params": {"name": name, "arguments": arguments}},
        timeout=120,
    )
    reply.raise_for_status()
    # The reply is one server-sent event: "event: message" then "data: {...}".
    data = next(line[6:] for line in reply.text.splitlines() if line.startswith("data: "))
    result = json.loads(data)["result"]
    text = result["content"][0]["text"]
    if result.get("isError"):
        raise RuntimeError(text)
    return json.loads(text)

hits = toolfare("search_capabilities", {"query": "website traffic", "limit": 5})
run = toolfare("call_capability", {
    "tool_name": "ahrefs_site_metrics",
    "arguments": {"target": "linear.app", "date": "2026-10-26"},
    "max_cost": 40,
})
print(run["data"]["content"], run["billing"]["charged_credits"])

MCP SDKs work too: point a streamable-HTTP client at the endpoint with the same Authorization header.

From a shell: the CLI

The same calls from a terminal or a cron job. One file, Node 18 or newer; JSON in, JSON out with --json. On a server, set TOOLFARE_API_KEY instead of signing in.

mkdir -p ~/.local/bin
curl -fsSL 'https://toolfare.ai/toolfare/toolfare.mjs' -o ~/.local/bin/toolfare
chmod +x ~/.local/bin/toolfare
export PATH="$HOME/.local/bin:$PATH"

toolfare login

toolfare discover "website traffic" --limit 5 --json
toolfare inspect ahrefs_site_metrics --json
toolfare run ahrefs_site_metrics -i target=linear.app -i date=2026-10-26 --max-cost 40 --json
toolfare balance --json

• --input '{...}', --input @file.json or repeated -i key=value pass the tool’s arguments.
• --max-cost <credits> refuses a call quoted above it, before anything is bought.
• --idempotency-key <key> charges a paid call at most once; read the reply before retrying.
• TOOLFARE_API_KEY replaces toolfare login on servers and CI.

Pricing and billing

• Your balance and top-ups are in US dollars. Quotes, max_cost and the billing fields count credits: 1,000 credits = $3, $0.003 each; charged_usd gives the dollar figure.
• Top up any whole-dollar amount from $3 to $1,000. No subscription. Top up more, get more: +5% from $75, +10% from $150, +15% from $300, added to the balance.
• Balance you top up never expires, and unused bought balance is refundable anytime. Free signup credits expire 7 days after signup and are not refundable.
• Every tool’s price is in its search result and description. Search, describe and balance are free.
• A paid call is quoted first and refused above max_cost. Metered vendors settle at the real cost of the call, so the charge can land slightly under or over the quote; billing in the reply has both.
• Failed calls are not charged. New accounts get $1.00 in free credits for data tools anywhere and watermarked video previews in the website Playground, valid for 7 days after signup. Video through an agent, the CLI or the API needs a first top-up, from $3.

Per-tool prices: Tools · Top-ups: Pricing

Errors

over_max_cost

The quote is above the max_cost you passed. Nothing ran and nothing was charged.

insufficient_credits

The balance does not cover the quote. The refusal carries buy_credits_url.

purchase_required

Video through an agent, the CLI or the API needs a first top-up, from $3. Free credits can make watermarked video previews in the website Playground.

free_daily_cap

Today’s site-wide free credits are used up. They refresh at 00:00 UTC; use paid balance or top up to continue now.

grant_busy

Another paid call on the same sign-in or key held the line for over 20 seconds. Nothing ran; retry it on its own.

provider_error

The vendor failed the request. It is not charged; retry once later, and do not loop paid retries.

provider_unreachable

The vendor could not be reached. Not charged.

budget_per_call

Above the per-call limit set for this app or key in the console.

401 invalid_token

Missing, expired or removed sign-in or API key.

Tool reference

Every plugin, with the tool names to pass as tool_name. Each page has parameter names and catalogue estimates; your agent can read the same as Markdown at /<plugin>.md.

• Ad Library

  ad_library_creatives_brands · ad_library_creatives_search · ad_library_google_ads · ad_library_linkedin_ads · ad_library_performance_ads · ad_library_performance_advertisers · ad_library_performance_advertisers_detail

• Ahrefs

  ahrefs_backlinks · ahrefs_backlinks_stats · ahrefs_domain_rating · ahrefs_keywords_overview · ahrefs_matching_terms · ahrefs_refdomains · ahrefs_site_metrics

• App Intelligence

  app_intel_apps_keywords · app_intel_apps_metadata · app_intel_apps_reviews · app_intel_keywords_apps · app_intel_keywords_metrics

• Audio Generation

  audio_generation_music · audio_generation_voice_changes

• Avatar Video

  avatar_video

• Avatars

  avatars_list

• Bilibili Data

  bilibili_data_profile · bilibili_data_search · bilibili_data_user_videos · bilibili_data_video · bilibili_data_video_comments

• Company Enrich

  company_enrich_email · company_enrich_ip

• Douyin Data

  douyin_data_profile · douyin_data_search · douyin_data_user_videos · douyin_data_video · douyin_data_video_comments

• Dubbing

  dubbing_dubs

• Image Editing

  image_editing · image_editing_edit

• Image Generation

  image_generation · image_generation_edit

• Instagram Data

  instagram_data_post · instagram_data_profile · instagram_data_search_users · instagram_data_user_posts · instagram_data_user_reels

• Kuaishou Data

  kuaishou_data_profile · kuaishou_data_search · kuaishou_data_user_hot_posts · kuaishou_data_video

• LinkedIn Data

  linkedin_data_company · linkedin_data_company_employees · linkedin_data_company_posts · linkedin_data_post_comments · linkedin_data_profile · linkedin_data_user_posts

• PageSpeed

  pagespeed_run

• Screenshot

  screenshot_take

• Seedance

  seedance_video

• Seedream

  seedream_image · seedream_image_edit

• Search Results

  serp_google_organic

• Similarweb

  similarweb_ad_networks · similarweb_audience_interest · similarweb_deduplicated_audience · similarweb_keyword_competitors · similarweb_landing_pages · similarweb_marketing_channels · similarweb_popular_pages · similarweb_referrals · similarweb_serp_players_aggregated · similarweb_serp_players_timeseries · similarweb_similar_sites · similarweb_subdomains · similarweb_top_sites_ranking · similarweb_website_ppc_spend · similarweb_website_ranking · similarweb_website_top_geographies · similarweb_website_traffic · similarweb_website_traffic_snapshot · similarweb_website_traffic_trend

• Text to Speech

  text_to_speech_speech · text_to_speech_voices

• Threads Data

  threads_data_post · threads_data_profile · threads_data_search · threads_data_user_posts

• TikTok Data

  tiktok_data_hashtag_detail · tiktok_data_hashtag_scrape · tiktok_data_hashtag_search · tiktok_data_hashtag_videos · tiktok_data_profile_videos · tiktok_data_search

• Transcription

  transcription_transcribe

• URL to Video

  url_to_video_links · url_to_video_videos

• Video Editing

  video_editing

• Video Generation

  video_generation

• Web Answer

  web_answer_answer

• Web Crawl

  web_crawl_crawls

• Web Reader

  web_reader_read

• Web Search

  web_search

• Weibo Data

  weibo_data_hot_search · weibo_data_post · weibo_data_profile · weibo_data_search · weibo_data_user_posts

• X Data

  x_data_post · x_data_search · x_data_user_posts

• Xiaohongshu Data

  xiaohongshu_data_note · xiaohongshu_data_note_comments · xiaohongshu_data_profile · xiaohongshu_data_search_notes · xiaohongshu_data_search_users · xiaohongshu_data_user_notes

• YouTube Data

  youtube_data_channel_id · youtube_data_channel_videos · youtube_data_search · youtube_data_video