MCP tool reference

The FreshlyCited MCP server at https://freshlycited.com/mcp exposes 49 tools. This page is generated from the server's own tool definitions, so it always matches what your client sees in tools/list. API names stay technical: a push is an index job, a visibility check is an index check.

Every tool works with the permissions of the API key or OAuth connection: tools above your role are listed but return 403. Read-only connections (scope mcp:read) can only call read-only tools. Each call counts against your rate limits (60 calls a minute per key; MCP is included on Agency Pro and Scale); tools that spend credits weigh 5 units and ask for confirm_spend: true above 1,000 credits.

Getting started

Who you are, what things cost, what to do next.

get_started

Get started. Start here. Returns who you are (role, workspace, plan, index and check credit balances), what you've done so far, rate limits, pricing and the next steps that fit this account (first check, smart push, IndexNow setup, sharing a report), with links to the docs.

No parameters.

First call in a new session:

{
  "name": "get_started",
  "arguments": {}
}

whoami

Who am I. Identity behind this key or connection: kind (user/apikey), id, workspace (tenantId), role, plan rate limits and, for OAuth connections, the app and scope.

No parameters.

Identity:

{
  "name": "whoami",
  "arguments": {}
}

get_pricing

Pricing and limits. Prices and limits. Two credit kinds: index credits (1 per URL pushed, reserved at submission, used only if Google indexes it; not indexed after 7 days → the credit comes back automatically; re-checks on day 1, 3, 7 are free) and check credits (1 per Standard check, 5 per Live check). IndexNow (Bing) submissions are free. Returns pricing (credits per action: { index, priority, check, liveCheck }; the priority lane is not sold yet), the packs and plans in USD, the guarantee rules, URLs per job (Free 50, paid 10,000) and API rate limits.

No parameters.

Pricing:

{
  "name": "get_pricing",
  "arguments": {}
}

Pushes (index jobs)

Send links to Google (and to Bing via IndexNow for verified sites), track them, push again.

validate_urls

Validate URLs. Validate and de-duplicate a URL list without spending credits. Returns how many are accepted, invalid and duplicated, with up to 10 invalid samples. Use before submit_index_job or check_index when the list came from a user paste or a file.

Clean a pasted list:

{
  "name": "validate_urls",
  "arguments": {
    "urls": [
      "https://example.com/blog/new-post",
      "https://example.com/pricing",
      "example.com/no-scheme",
      "https://example.com/blog/new-post"
    ]
  }
}

preflight_urls

Pre-flight URLs before pushing. Free pre-flight for up to 1,000 URLs: fetches each page (as a crawler would) and flags ones Google can't index at that address: HTTP 4xx/5xx or unreachable, noindex (meta or X-Robots-Tag), blocked by robots.txt for Googlebot, redirects, canonical pointing elsewhere. submit_index_job skips flagged URLs for free by default (push_anyway overrides; then their credit is used). Results are cached for 6 hours, so a push right after reuses them.

Check a list before pushing:

{
  "name": "preflight_urls",
  "arguments": {
    "urls": [
      "https://example.com/blog/new-post",
      "https://example.com/pricing"
    ]
  }
}

submit_index_job

Push links to Google (index job). Push up to 10,000 URLs so Google crawls them (an "index job"). Each URL reserves 1 index credit, used only if Google indexes it: FreshlyCited re-checks on day 1, 3, 7 (free) and gives the credit back automatically if the link still isn't indexed after day 7. Not covered (credit used): pages that return 404/410/5xx, are noindex, blocked by robots.txt, redirect, have a canonical pointing elsewhere, or that you remove. A free pre-flight runs first and skips flagged URLs (see preflight_urls; response field preflight). Recommended: smart=true checks every URL first (1 check credit/URL) and only pushes the ones Google doesn't show yet; their reserved index credit comes straight back. drip_days spreads the push over 1-30 days. URLs on a site you verified for IndexNow are ALSO sent to Bing and the other IndexNow engines for free (not to Google, ChatGPT or Perplexity); a URL sent to IndexNow in the last 24 h isn't resent unless indexnow_force=true. Returns the job with an outcome headline, credits { index: { reserved, consumed, released, excluded } } and the guarantee's next re-check. Spends credits: calls above the confirmation threshold need confirm_spend=true.

Smart push:

{
  "name": "submit_index_job",
  "arguments": {
    "urls": [
      "https://example.com/blog/new-post",
      "https://example.com/pricing"
    ],
    "smart": true,
    "name": "October posts"
  }
}

Drip 500 backlinks over 7 days:

{
  "name": "submit_index_job",
  "arguments": {
    "urls": [
      "https://guest-blog.example.net/post-about-you"
    ],
    "drip_days": 7
  }
}

get_job_status

Get push or check. Full status of one push or visibility check: outcome headline (e.g. '11 of 12 links seen by Google (+2)'), stage, drip progress, before/after comparison, credits (index: reserved / consumed / released / excluded; check credits used), the guarantee's next re-check, pre-flight counts, ledger lines, IndexNow (Bing) summary and the first URLs (each with credit_state). sync=true refreshes crawl status from the network first (cheap, no credits).

Status with 10 URLs:

{
  "name": "get_job_status",
  "arguments": {
    "job_id": "job_0123456789abcdef",
    "url_limit": 10
  }
}

list_jobs

List pushes and checks. List pushes (type=index) and visibility checks (type=check) in scope, newest first, each with its outcome and index credits reserved / consumed / released. Paginated: returns { items, total, page, page_size }.

Last 10 pushes:

{
  "name": "list_jobs",
  "arguments": {
    "type": "index",
    "page_size": 10
  }
}

list_job_urls

List a job's links. List the links of one push or check with filters: state (pending, queued, completed, failed, skipped, …), indexed (yes = seen by Google, no = invisible, unknown = not checked) and credit (reserved, consumed, released, excluded). Each row includes the latest Google position/title, the guarantee fields (credit_state, sent_at, next_recheck_at, recheck_n, excluded_reason), the pre-flight flag, the IndexNow state and the Bing check result.

Links Google still can't see:

{
  "name": "list_job_urls",
  "arguments": {
    "job_id": "job_0123456789abcdef",
    "indexed": "no"
  }
}

Credits returned:

{
  "name": "list_job_urls",
  "arguments": {
    "job_id": "job_0123456789abcdef",
    "credit": "released"
  }
}

update_job

Rename a job. Rename a push or check. (recheck_days is accepted for compatibility; guarantee re-checks on day 1, 3 and 7 are automatic.)

Rename:

{
  "name": "update_job",
  "arguments": {
    "job_id": "job_0123456789abcdef",
    "name": "October citations"
  }
}

cancel_job

Cancel a job. Cancel a running or dripping push/check. Links not sent yet get their index credit back; links already pushed can't be recalled and keep their 7-day guarantee.

Cancel:

{
  "name": "cancel_job",
  "arguments": {
    "job_id": "job_0123456789abcdef"
  }
}

retry_job

Push failed links again. Re-push a job's failed or cancelled links as a new push (1 index credit reserved per link, same guarantee). Counts as an explicit re-push for IndexNow.

Retry:

{
  "name": "retry_job",
  "arguments": {
    "job_id": "job_0123456789abcdef"
  }
}

send_unindexed_to_indexer

Push the invisible links again. One step: start a new push with only the links Google can't see in this job's latest check (indexed=no). 1 index credit reserved per link, same guarantee. The latest check becomes the 'before' for the visibility lift. Counts as an explicit re-push for IndexNow.

Push again:

{
  "name": "send_unindexed_to_indexer",
  "arguments": {
    "job_id": "job_0123456789abcdef"
  }
}

delete_job

Delete a job. Permanently delete a finished or cancelled push/check, its link results and any shared report link. Credits are not refunded; links still inside their 7-day guarantee count as removed by you (credit used).

Delete:

{
  "name": "delete_job",
  "arguments": {
    "job_id": "job_0123456789abcdef"
  }
}

delete_job_url

Remove one link. Remove one link (by its numeric url id from list_job_urls) from a finished job. A link still inside its guarantee counts as removed by you (credit used).

Remove:

{
  "name": "delete_job_url",
  "arguments": {
    "job_id": "job_0123456789abcdef",
    "url_id": 42
  }
}

Visibility checks (index checks)

Ask Google (and Bing) whether links are indexed, and read the stored results.

check_index

Visibility check (index check). Check whether URLs are indexed (1 check credit/URL with Pilot Scan: Standard, 5 with Live; up to 10,000, Free plan 50). Pass urls to create a new check, or job_id to re-check an existing push/check (manual re-checks are charged; the guarantee's own re-checks are free). engine: scan_standard (default queue, may take minutes; poll get_job_status), scan_live (seconds; monthly Live quota on Agency plans), scan_bing (positive-only "Seen by Bing" for an existing job: confirms links Bing shows, misses are returned and read "not confirmed"; off unless the platform enabled it). A check that finds a pushed link indexed uses its reserved index credit. Returns the job; results land on each link as indexed / bing_indexed.

Check two pages:

{
  "name": "check_index",
  "arguments": {
    "urls": [
      "https://example.com/blog/new-post",
      "https://example.com/pricing"
    ]
  }
}

Is a push in Bing yet?:

{
  "name": "check_index",
  "arguments": {
    "job_id": "job_0123456789abcdef",
    "engine": "scan_bing"
  }
}

get_check_results

Stored search results. Stored search data for a job's links: indexed, position, title, snippet, displayed URL, SERP features, match type, query, total results and the engine (Google or Bing). Pass url for one link's full history.

All results:

{
  "name": "get_check_results",
  "arguments": {
    "job_id": "job_0123456789abcdef"
  }
}

One link's history:

{
  "name": "get_check_results",
  "arguments": {
    "job_id": "job_0123456789abcdef",
    "url": "https://example.com/blog/new-post"
  }
}

share_job_report

Share a client report. Create (or return the existing) read-only client report link for a job: before/after visibility, per-link status, no login needed. Your branding on Agency plans; FreshlyCited-branded on Free. revoke=true stops sharing.

Share:

{
  "name": "share_job_report",
  "arguments": {
    "job_id": "job_0123456789abcdef"
  }
}

export_job_csv

Export CSV. Export a job's links with submission state, before/after index status, index credit state and the latest search data as CSV text ({ filename, csv }).

Export:

{
  "name": "export_job_csv",
  "arguments": {
    "job_id": "job_0123456789abcdef"
  }
}

Bing & Copilot (IndexNow)

Verify your sites for IndexNow so pushes also notify Bing and the other IndexNow engines. Free.

list_indexnow_sites

List IndexNow sites. List the sites (hosts) registered for IndexNow in scope, with verification state, the key, where the key file must be hosted (key_file_url) and how many links went to IndexNow in the last 30 days. A site pings IndexNow only when verified=true and enabled=true (active).

All sites:

{
  "name": "list_indexnow_sites",
  "arguments": {}
}

add_indexnow_site

Add a site for IndexNow. Register a host (e.g. example.com or www.example.com; one entry per exact hostname) for IndexNow. Returns a generated key and key_file_url: the site owner must publish a plain-text file at that URL containing only the key (or set key_location to a .txt file elsewhere on the same host; it then only covers URLs under that folder). Then call verify_indexnow_site. Free.

Add a domain:

{
  "name": "add_indexnow_site",
  "arguments": {
    "host": "www.example.com"
  }
}

verify_indexnow_site

Verify an IndexNow site. Fetch the site's key file now and mark the site verified if it contains exactly the key. Returns verification { ok, url, detail } in plain language (e.g. 'The key file isn't there yet (HTTP 404 …)'). Verified sites are re-checked daily; two failures in a row pause pings with a notice.

Verify:

{
  "name": "verify_indexnow_site",
  "arguments": {
    "site_id": "site_0123456789abcdef"
  }
}

update_indexnow_site

Turn a site on/off or move its key file. Switch IndexNow pings for a site on or off (enabled), or change key_location (null = the root /<key>.txt). Changing the key location requires verifying again.

Pause pings:

{
  "name": "update_indexnow_site",
  "arguments": {
    "site_id": "site_0123456789abcdef",
    "enabled": false
  }
}

delete_indexnow_site

Remove an IndexNow site. Remove a site from IndexNow. Pushes stop notifying IndexNow for that host; past submission records stay on the jobs.

Remove:

{
  "name": "delete_indexnow_site",
  "arguments": {
    "site_id": "site_0123456789abcdef"
  }
}

get_job_indexnow

IndexNow status of a push. What a push sent to IndexNow: summary { sent, accepted (HTTP 200), pending (HTTP 202, key still being validated), errors, skipped_recent (sent < 24 h ago, not resent), bing_seen, bing_not, hosts, http_codes } and per-link rows (indexnow_state, indexnow_http, indexnow_at, bing_indexed). Links on hosts that aren't verified are never sent to IndexNow.

Status:

{
  "name": "get_job_indexnow",
  "arguments": {
    "job_id": "job_0123456789abcdef"
  }
}

Clients & members

Your agency, client workspaces and who can access them.

list_tenants

List workspaces. List your workspace and every client/team under it in tree order (depth, path) with credits, member and job counts.

Clients only:

{
  "name": "list_tenants",
  "arguments": {
    "kind": "client"
  }
}

list_sub_tenants

List direct sub-workspaces. List the direct children of one workspace.

Children of mine:

{
  "name": "list_sub_tenants",
  "arguments": {}
}

get_tenant

Get a workspace. One workspace with credits, counts, parent and whether it's your root.

Get:

{
  "name": "get_tenant",
  "arguments": {
    "tenant_id": "ten_0123456789abcdef"
  }
}

create_sub_tenant

Create a client workspace. Create a client (default) or team workspace under yours (or under parent_id). It starts with 0 credits: use allocate_credits.

New client:

{
  "name": "create_sub_tenant",
  "arguments": {
    "name": "Acme Dental",
    "kind": "client"
  }
}

update_tenant

Update a workspace. Rename, change kind or notes, set the default re-check days (0-5), move under another parent, or archive/restore a workspace.

Default re-check 3 days:

{
  "name": "update_tenant",
  "arguments": {
    "tenant_id": "ten_0123456789abcdef",
    "default_recheck_days": 3
  }
}

delete_tenant

Delete or archive a workspace. Delete an EMPTY workspace (confirm must equal its exact name) or archive it (mode=archive). Workspaces with jobs, credits or children can only be archived.

Archive:

{
  "name": "delete_tenant",
  "arguments": {
    "tenant_id": "ten_0123456789abcdef",
    "mode": "archive"
  }
}

list_members

List members. People with access to a workspace and their roles.

Members:

{
  "name": "list_members",
  "arguments": {}
}

add_member

Add a member. Give a person access to a workspace with a role (owner, admin, member, client_viewer = read-only). Creates and invites the account if the email is new.

Read-only client login:

{
  "name": "add_member",
  "arguments": {
    "email": "client@acme.example",
    "tenant_id": "ten_0123456789abcdef",
    "role": "client_viewer"
  }
}

update_member_role

Change a member's role. Change a member's role (never above your own).

Make admin:

{
  "name": "update_member_role",
  "arguments": {
    "tenant_id": "ten_0123456789abcdef",
    "user_id": "usr_0123456789abcdef",
    "role": "admin"
  }
}

remove_member

Remove a member. Remove a person's access to a workspace (the last owner can't be removed).

Remove:

{
  "name": "remove_member",
  "arguments": {
    "tenant_id": "ten_0123456789abcdef",
    "user_id": "usr_0123456789abcdef"
  }
}

Credits

Balances, the ledger and moving credits to clients.

get_credits

Credit balance. A workspace's balances { index, check, reservedIndex } (index credits reserved by pushes are waiting for the guarantee), the plan with its limits and what's used, usage this period, credits expiring in the next 30 days, pricing and the 20 most recent ledger lines.

My balance:

{
  "name": "get_credits",
  "arguments": {}
}

list_ledger

Credit ledger. Paginated, append-only credit ledger in scope: grants (purchase, plan_grant, admin), reserve / consume / release / excluded for pushes, check usage, expiries and transfers (allocate). kind=index|check filters the credit kind; direction=in|out filters credits received or spent.

Check spending:

{
  "name": "list_ledger",
  "arguments": {
    "kind": "check",
    "direction": "out"
  }
}

allocate_credits

Give credits to a client. Move index or check credits from a parent workspace to a sub-workspace (negative amount pulls credits back). Each moved credit keeps its expiry. Platform admins may also grant to a root workspace.

Give 500 index credits:

{
  "name": "allocate_credits",
  "arguments": {
    "tenant_id": "ten_0123456789abcdef",
    "amount": 500,
    "kind": "index",
    "note": "October"
  }
}

reverse_ledger_entry

Reverse a transfer. Reverse a transfer to a client (while those credits are unspent) or a platform-admin adjustment. Push and check credits settle automatically and can't be reversed.

Reverse:

{
  "name": "reverse_ledger_entry",
  "arguments": {
    "entry_id": 1234
  }
}

API keys

Create, limit and revoke API keys.

list_api_keys

List API keys. API keys in scope (prefix only, never the secret) with role, rate limits, last use and status.

Active keys:

{
  "name": "list_api_keys",
  "arguments": {
    "status": "active"
  }
}

create_api_key

Create an API key. Create an API key for a workspace. The secret (ipk_…) is returned once. Optional per-key limits: rate_per_min, rate_per_day (requests) and daily_credit_cap (credits per UTC day).

Read-only key for a client dashboard:

{
  "name": "create_api_key",
  "arguments": {
    "name": "Looker",
    "role": "client_viewer",
    "rate_per_min": 30
  }
}

update_api_key

Update an API key. Rename, change role or change the key's rate limits / daily credit cap (null = default).

Cap spend:

{
  "name": "update_api_key",
  "arguments": {
    "key_id": "key_0123456789abcdef",
    "daily_credit_cap": 2000
  }
}

revoke_api_key

Revoke an API key. Revoke a key immediately (it stays listed for audit). A key can't revoke itself.

Revoke:

{
  "name": "revoke_api_key",
  "arguments": {
    "key_id": "key_0123456789abcdef"
  }
}

delete_api_key

Delete an API key. Permanently delete a key.

Delete:

{
  "name": "delete_api_key",
  "arguments": {
    "key_id": "key_0123456789abcdef"
  }
}

Platform admin

Only for FreshlyCited platform administrators.

list_users

List users. Platform admin: list user accounts.

Suspended:

{
  "name": "list_users",
  "arguments": {
    "status": "suspended"
  }
}

get_user

Get a user. Platform admin: one user's memberships, sessions, activity and keys.

Get:

{
  "name": "get_user",
  "arguments": {
    "user_id": "usr_0123456789abcdef"
  }
}

list_errors

List tracked errors. Platform admin: tracked server/API/MCP errors.

Open errors:

{
  "name": "list_errors",
  "arguments": {
    "status": "open"
  }
}

resolve_error

Resolve an error. Platform admin: mark an error resolved or open again.

Resolve:

{
  "name": "resolve_error",
  "arguments": {
    "error_id": "err_0123456789abcdef",
    "resolved": true
  }
}

list_audit_log

Audit log. Platform admin: the audit trail.

IndexNow events:

{
  "name": "list_audit_log",
  "arguments": {
    "action": "indexnow.site_paused"
  }
}