The HTTP guide shows a curl call and the fields to keep. This page is the agent path. Connect MCP with the same vf_live_ key, call get_account, then call lookup_domain for two public domains and write down the status the snapshot returns, including missing. Use compare_bulk when several hosts belong in one pass, and lookup_keyword when the question is a US/EN query.
Connect the server, then read the account
The MCP endpoint is POST /mcp on the site origin. For the public site that is https://vaneform.com/mcp. initialize and tools/list are open. Every tools/call needs a vf_live_ key, the same key the HTTP API accepts, in an Authorization: Bearer header. The signed-in API desk at /account/api has an MCP tab that fills Cursor, Claude and Codex snippets with the origin of the page you are on. The snippets below use the public origin and the placeholder vf_live_…. Create the key on that desk and put it in the client header or, for Codex, in VANEFORM_API_KEY. The published skill file at /skill.md tells you to keep the key out of SKILL.md.
After the client lists the tools, call get_account before a batch. The call spends 0 credits. The account payload includes plan, access_tier, the website lookup allowance (used, limit, remaining, resets_at) and credits (used, limit, remaining, resets_at, top_up_remaining). Read that payload as the budget for the calls below. Checked 2026-10-24, Free includes 100 credits a UTC month and Pro includes 10,000. A key allows 60 requests a minute and 5,000 a day; past that the server returns 429 lookup_rate_exceeded and a Retry-After header when it has one.
{
"mcpServers": {
"vaneform": {
"url": "https://vaneform.com/mcp",
"headers": { "Authorization": "Bearer vf_live_…" }
}
}
}
claude mcp add --transport http --scope user vaneform https://vaneform.com/mcp --header "Authorization: Bearer vf_live_…"
export VANEFORM_API_KEY=vf_live_…
codex mcp add vaneform --url https://vaneform.com/mcp --bearer-token-env-var VANEFORM_API_KEYCall lookup_domain and keep the status you receive
Call lookup_domain twice. First set domain to google.com. Then set domain to example.com. Leave include at the default families, which are scale, registry, profile and popularity. A leading www. is removed and the host is lowercased before the cache is read, so www.google.com and google.com ask for the same host. Optional include=baidu adds the cached Baidu rank and is available on Free. Optional include=search adds Pro-only keyword rankings (ranked keywords, landing pages, search competitors) from the saved month. This walkthrough stays on the default four families.
Read the resource status before any visit field. status=missing means the cache has no snapshot for that host. Leave visits empty and record missing. A ready or partial snapshot can include scale. When scale is present, keep estimate (site or search), visits, month, as_of and confidence next to the number. The domain read is cache-only: refresh_policy on this call stays cache_only, and a second identical call does not buy an upstream fill. Write the retrieval time in your own note, separate from month and as_of. Whatever google.com and example.com return on the day you run this is the observation; this guide does not supply a visit count for either host.
More in this section
Checked 2026-10-24, a new ready or partial domain spends 1 credit. With include=search the server charges 200 credits when the domain resource is ready or partial and the saved ranking is absent or has status ready. It spends 0 when that saved ranking status is missing, error or partial, and it spends 0 when the domain resource itself is missing or error. A lookup receipt from the previous 24 hours for the same account, host and charge kind (lookup, or advanced when search is included) spends 0. A Free key that sends include=search receives 403 search_requires_pro. Re-check the live amounts on the API documentation; that page renders the current credit constants.
get_account
lookup_domain
domain: google.com
include: scale,registry,profile,popularity
lookup_domain
domain: example.com
include: scale,registry,profile,popularityWhich tool does which job
The MCP tool list names the job in each description. The credit column is the charge the server applies for that job, from the credit constants and the lookup path, as checked on 2026-10-24. A row that says 0 still returns the payload’s own status, coverage and dates. Research tools are the five calls whose descriptions say they spend 0: research_site, get_research_workspace, save_research, monitor_research and manage_research.
| Tool | Job | Credits |
|---|---|---|
| lookup_domain | Cached snapshot: scale, registry, profile, popularity. Optional baidu. Optional Pro search. status=missing means the cache has no snapshot. | 1 for a new ready or partial domain. include=search: 200 when the domain is ready or partial and the saved ranking is absent or ready; 0 when that saved status is missing, error or partial. A 24-hour receipt for that charge kind spends 0. |
| get_account | Plan, website lookup allowance and credit balance. Call it before a batch. | 0 |
| lookup_keyword | US/EN keyword brief: monthly searches, difficulty, CPC and Google occupancy. At most 30 Google results. Pro only. | A cache hit whose status is ready or empty spends 0. A miss that returns status ready spends 60. |
| compare_bulk | Scale and registry for many domains. Fetches scale when monthly visits are missing, and registry when that record needs a refresh. Duplicates are kept once. Free 3 domains, Pro 30. | 1 per compared domain whose scale or registry is ready or partial. A domain with a lookup receipt from the last 24 hours spends 0. |
| compare_tld | The same registrable name across suffixes. Default suffixes are com, ai, io. example.com is read as example. Response order follows the returned suffixes list. | 1 per compared domain with scale or registry data, with the same 24-hour receipt as compare_bulk. |
| research_site | Free early-access research. tool is one of site-overview, google-ads, adsense, meta-ads, outbound-links, ad-keywords, discovery, dr-growth, with q and the optional filters named on the tool. | 0. The response includes credits_spent: 0. |
| get_research_workspace | Saved research, folders, private notes, tool history, monitors and in-app change notifications for the authenticated account. | 0 |
| save_research | Save a site-tool query with label, folder and notes. The skill file caps saves at 200 targets for one account. | 0 |
| monitor_research | Watch a Google Ads or AdSense query daily or weekly. interval_days is 1 or 7. The skill file caps monitors at 50 targets for one account. | 0 |
| manage_research | remove_save, update_monitor, remove_monitor, check_monitor or read_event, using an id from get_research_workspace. | 0 |
Run compare_bulk on the hosts you already named
When the question is “these hosts, side by side”, call compare_bulk with q set to the domains separated by commas or newlines. google.com,example.com is enough for a first pass. Duplicate hosts are kept once. The tool returns scale and registry. Where monthly visits are missing it fetches scale, and where the registry record needs a refresh it fetches that record. Domain lookup_domain stays cache-only; this compare path is the one that can fill a missing monthly-visit figure. Read each returned item’s scale status and registry status. A skipped host can appear with reason lookup_failed while the other rows still return.
Free accounts compare up to 3 domains and Pro accounts up to 30, the same caps as the website comparison page. A longer list returns invalid_request and the message states the cap. Each compared domain whose scale or registry is ready or partial spends 1 credit, unless that host already has a lookup receipt from the last 24 hours. Call get_account again after the compare if the batch is large enough that the remaining balance matters. The human page for the same job is /bulk.
compare_bulk
q: google.com,example.comUse lookup_keyword for a search query
lookup_keyword answers a query. The market is US/EN: the default market id is us and the language code is en. Pass q, for example website traffic. After trimming, a string longer than 200 characters is invalid. Matching and the returned keyword use the lowercased, space-collapsed first 80 characters. The brief can include monthly searches, difficulty, CPC and Google occupancy, and the tool description caps the Google sample at 30 results. A cached snapshot whose status is ready or empty spends 0. A cache miss that comes back with status ready spends 60 credits. status=empty means the result has no rows and spends 0. A Free key receives 403 pro_required.
A Chinese phrase can be the text of q, and the market on this tool remains US/EN. Domain rankings are a different call: lookup_domain with include=search, Pro only, reading the saved rankings for that host. Use lookup_keyword when you have a query and no host yet. Use include=search when you already have the host and need its ranked keywords, landing pages and search competitors from the saved month. The keyword page on the site is /keyword.
lookup_keyword
q: website trafficPlan gates, research tools and a short balance
The five research tools spend 0 credits. research_site takes tool and q. Its tool enum is site-overview, google-ads, adsense, meta-ads, outbound-links, ad-keywords, discovery and dr-growth. Optional arguments include mode, region, limit from 1 to 100, visit, DR and age filters, and a returned cursor. get_research_workspace reads saves, history, monitors and change events for the authenticated account. save_research stores a query with label, folder and notes. monitor_research watches a Google Ads or AdSense query on interval_days 1 or 7. manage_research takes action and an id from that workspace: remove_save, update_monitor, remove_monitor, check_monitor or read_event. The skill file states two caps the tool descriptions leave unnamed: 200 saved targets and 50 monitors on one account. Saves and monitors stay private to that account.
Keyword lookup and include=search stay on Pro. A Free key gets pro_required or search_requires_pro, plus upgrade_url on those responses. credits_exhausted means the balance cannot cover the charge; repeating the same call leaves it exhausted. invalid_domain and invalid_request are argument problems: fix the host or the include list, where include must be a comma-separated set drawn from scale, registry, profile, popularity, baidu and search. The open-source MCP repository documents the server. The HTTP guide remains the place for the curl example and the scale field list, and the Python guide remains the place for a CSV file.
Sources (1)
After the payload, open the page that matches the question
Lead the note with the domain or the keyword, the status, and the numbers that are actually in the payload. When report_url is present, keep the link. When status is missing, the note says missing and names the host. The AI referral board answers a different question from this snapshot: which sites are gaining estimated visits from generative assistants, with that board’s month and scope. Open it when the agent task is about assistant referrals. Open /bulk when you want the same compare on screen, and /keyword when you want the US/EN brief in the browser.
Keep a missing visit blank, and keep an older as_of on its own date. Store the family status beside the value, then ask the next tool only for the job in the table. The HTTP guide is the field-by-field companion. This page ends when the agent can repeat the two lookup_domain calls, record a missing row as missing, and choose compare_bulk or lookup_keyword for the following question.