Saylent

The MCP server

Let an agent run the whole loop itself - ten tools on stdio, the same pipeline, the same cost guard.

saylent mcp runs a Model Context Protocol server on stdio, so an agent can audit a brand, verify a fix, check bot access, read an existing report, ask where its answers came from, list the drafted fixes with their evidence, compare runs, export the data, read your access log for AI crawlers and preview a question import itself. It is the same pipeline the CLI runs: same key resolution, same cost estimate before the spend, same max_usd refusal, same summary blocks - handed to the agent as JSON instead of rendered to HTML.

The ten tools

ToolWhat it doesCost
auditFull audit of a domain. Writes run.json, report.html, report.md; returns the verdict, the recommended band, the summary blocks, the file paths and the real costYour own credits: about $0.80 to $1.20 with four engines (smoke; our recorded runs cost $0.93 and $1.11) or $5.10 to $7.10 (full)
verifyRe-asks the frozen questions of an existing run.json and writes movement.htmlYour own credits: about the same as the audit it re-runs
gate_checkrobots.txt per bot class, a live per-user-agent probe, JSON-LD, meta directives$0 - no keys, no model calls
read_reportThe summary blocks of a run.json already on disk, whole or one named section$0 - no network, no model calls
sourcesCitation share, share of voice and off-site opportunities of a run.json already on disk, with receipts$0 - no network, no model calls
fixesThe drafted fixes of a run.json, ranked, each with its evidence lines, engines, effort and whether saylent fixes apply can write it into a repo; fix returns one fix's full drafted artifact$0 - no network, no model calls
historyTwo or more runs of one brand: counts per run and engine, and what moved between the oldest and the newest as events with receipts (the same rules as Alerts)$0 - no network, no model calls
exportThe documented export tables (answers, citations, sources, opportunities, share of voice, fixes, crawlers): one table inline, or files with out_dir$0 - no network, no model calls
crawlersWhich AI crawlers visit, from an access log in the working directory: bots, purposes, pages, blocks and errors with redacted log lines; with run_path, the cited pages no AI crawler fetched$0 - no model calls; network only with verify_ips (the operators' public IP lists)
questions_importPreview turning a Search Console export, a CSV or text lines into audit questions: what would be kept and every drop reason. Writes nothing$0 - no network, no model calls

Every tool states its cost range in its own description, so the agent knows before it calls. audit and verify check the estimate against max_usd and the daily spend cap before anything reaches a provider, and refuse with the same message the CLI prints.

audit and verify arguments

audit and verify are built from ONE shared argument schema, the same one saylent audit/saylent verify's own flags are generated from (see the CLI reference's --flag column) - the two surfaces can never accept a different argument set. Only domain is required; everything else is optional. Pass dry_run: true on audit for a $0, no-keys, no-network preflight: the question set it would ask, which providers have a key (keys_configured, presence only, never a value), the engines a real run would ask (engines_with_keys), the judge mode, whether the run would start (ready_to_run) and the cost estimate for those engines. When the run asks an answer surface, keys_configured.serpapi says whether a SerpApi key is set, and a surfaces block lists the surfaces requested, the locale, the provider and, when the key is missing, the sentence a real run would refuse with. Nothing is sent to any provider.

A finished audit also returns sources_summary: the run's citation totals, its five most cited domains and its first three off-site opportunities. The sources tool below has the rest.

ArgumentTool(s)CLI flagDescription
domainaudit(positional)The brand's domain, for example example.com
brandaudit--brandBrand name (default: the domain)
competitorsaudit--competitorsCompetitor domains/names
profileaudit--profilesmoke (default, 6 questions) or full (23 questions)
enginesaudit--enginesWhich answer sources to ask: chatgpt, claude, gemini, perplexity, and the answer surfaces google_ai_overview, google_ai_mode, copilot (surfaces need SERPAPI_API_KEY)
surfacesaudit--surfacesAnswer surfaces to ADD to the engine set: google_ai_overview, google_ai_mode, copilot. Read through your SerpApi key (SERPAPI_API_KEY), billed per search by your SerpApi plan
countryaudit--countryCountry the answer surfaces are fetched for, two letters (e.g. "us", "de"). Surfaces only
locationaudit--locationCity-level location for the Google surfaces (e.g. "Austin, Texas, United States"). Surfaces only
questions_fileaudit--questionsPath to a run.json bundle, a questions.json (from saylent questions), or a text file with one question per line, to reuse instead of generating a new set
questionsaudit(none - MCP only)Inline question rows to ask instead of generating a set ({id?, type?, text, samples?}). The CLI takes a file path via the same --questions flag (questions_file above)
samplesaudit, verify--samplesHow many times each scored question is asked (1-5)
judgeaudit, verify--judgeJudge model; its provider family is inferred from the name
judge_familyaudit, verify--judge-familyanthropic | openai, when the judge model name is ambiguous
modelsaudit, verify--modelPer-role model overrides: brand, drafter, chatgpt, claude, gemini, perplexity
localeaudit, verify*--localeTranslate the generated question set into this language once (e.g. "de", "pt-BR"), via the drafter model. No effect when a question set is reused (questions_file/questions)
user_agentaudit, verify*--user-agentOverride the crawler's User-Agent for this run's fetches (crawl, corpus, domain checks)
max_pagesaudit, verify*--max-pagesCap how many crawled pages feed the brand model and corpus (1-200)
allow_privateaudit, verify*--allow-privateAllow the audited site's own host (and its www/apex sibling) to resolve to a private/internal address, for a staging server on your own network. Never on by default
skipaudit, verify*--skipSkip costly stages: drafts, corpus, gates ({drafts,corpus,gates} or a list of stage names)
max_usdaudit, verify--max-usdRefuse to run if the high cost estimate exceeds this many dollars
out_diraudit--outOutput directory (default: ./<domain>/<YYYY-MM-DD>/)
formataudit--formatWhich report files to write: md, html, json (default: all three)
dry_runaudit--dry-runPrint the plan, the questions it would ask (template defaults, $0, no crawl) and the cost estimate. Spends nothing
no_brand_modelaudit--no-brand-modelDocumented for parity with saylent questions; a dry run already always previews with template defaults, so this has no further effect on audit
bundle_pathverify(positional)Path to the baseline run.json (or the directory containing it)

* Accepted on verify for parity with audit (a client that always passes the same argument set to both tools shouldn't error), but have no effect: a verify re-asks the SAME frozen questions and never crawls, fetches corpus, checks gates, or generates a fresh question set.

read_report's section argument also accepts "questions", returning the run's frozen question set alongside the Brief's "hero" and card sections.

sources arguments

sources reads a run.json already on disk. It is free, read-only and makes no network call. The definitions behind every number are on Sources & opportunities.

ArgumentDescription
bundle_pathPath to a run.json (or the directory containing it). Required
view"summary" (default), "opportunities", "domains", "voice" or "all"
engineKeep only rows cited by this engine or answer surface id, for example "google_ai_overview"
typeKeep only domains of this type, for example "review_site"
domainOne domain's detail: its pages and every answer citing it
limitRows per list (default 10, max 50)

It returns totals, the per-engine summaries (engines), by_type, and the lists the view asks for: opportunities with their receipts (qid, engine, question, cited_urls, rivals_named with the reason each answer gave, and an answer_excerpt), domains, and voice. recomputed says whether the numbers came from the bundle's stored sources block or were computed from its rows. saylent sources <run.json> --json prints the same payload.

fixes, history and export arguments

fixes takes bundle_path (required) and fix, a fix_key from the list, for that fix's full drafted artifact. It returns every fix with evidence (the receipts the diagnosis recorded), engines, effort, weight, applies_to (site for robots.txt and JSON-LD changes, other for outreach and content) and site_fixes. It writes nothing; the user runs saylent fixes apply in a terminal to put the site fixes on a branch (CLI).

history takes bundle_paths (required): run.json files, run folders or a brand folder of <YYYY-MM-DD>/run.json, at least two runs of one brand. It returns runs (counts overall and per engine), compared (the change in recommended and mentioned answers, whether the questions and models were the same), movement.events (each with its question, engine and receipt) and the citation history per domain.

export takes bundle_paths (required), crawlers_path (a crawlers.json inside the working directory), table, format (json or csv), limit (rows returned inline, default 100) and out_dir (write files instead, inside the working directory). The columns are on Export and API.

crawlers and questions_import arguments

crawlers takes log_path (a file or directory inside the server's working directory; required), run_path (a run.json to join with), verify_ips, since, until and limit. It returns the summary sentence, totals, one row per bot, the top problems with one redacted log line each, spoofed, and join when a run was given. Client IPs are always redacted. Details: AI crawlers.

questions_import takes file_path (inside the working directory; required), format, column, min_impressions, exclude, include, questions_only, cluster, max, language and country, and returns the kept rows, the drop counts by reason and a one-line summary. It writes nothing: the user runs saylent questions import to keep the set. Details: Import questions.

Keys are never tool arguments. There is no key parameter on any tool. The server resolves provider keys exactly like the CLI: environment variables, then a .env in its working directory, then ~/.saylent/config.json. Put them in the server definition's env block, or run saylent keys once and leave the definition clean.

Connect a client

Every client below starts the same local stdio server, npx -y saylent mcp (Node 22 or newer). Saylent measures and hands back the receipts; your agent does the reasoning over them.

Keys: save them once, keep them out of client configs. Run npx saylent keys set openai (and anthropic, gemini, perplexity as you like) in your own terminal. The server reads ~/.saylent/config.json itself, so every config below works with no env block and no key in any file a client syncs or a shell history keeps. npx saylent keys set serpapi adds the answer surfaces the same way. The free tools (gate_check, read_report, sources, an audit with dry_run: true) need no key at all. If you would rather pass keys through the client, each section shows that client's own way to do it.

Claude Code

The quickest route is the Claude Code plugin: two commands install this server plus skills that check crawler access for free and preview an audit's cost before spending. To add only the server, for every project:

claude mcp add --transport stdio --scope user saylent -- npx -y saylent mcp

Everything after -- is the command that starts the server. --scope project writes a shareable .mcp.json instead, where ${VAR} expands from your environment, so a team can commit it without a key in it:

{
  "mcpServers": {
    "saylent": {
      "command": "npx",
      "args": ["-y", "saylent", "mcp"],
      "env": { "OPENAI_API_KEY": "${OPENAI_API_KEY:-}", "ANTHROPIC_API_KEY": "${ANTHROPIC_API_KEY:-}" }
    }
  }
}

Claude Desktop

Edit claude_desktop_config.json (macOS: ~/Library/Application Support/Claude/claude_desktop_config.json, Windows: %APPDATA%\Claude\claude_desktop_config.json), then restart the app:

{
  "mcpServers": {
    "saylent": {
      "command": "npx",
      "args": ["-y", "saylent", "mcp"]
    }
  }
}

Claude Desktop does not expand variables in this file: a key you add under env is stored there as plain text, which is why saylent keys is the better place for it.

Cursor

Add to Cursor installs it in one click (the link carries {"command":"npx","args":["-y","saylent","mcp"]}, base64-encoded, the format Cursor documents). By hand, the same shape goes in ~/.cursor/mcp.json (every project) or .cursor/mcp.json (this project only):

{
  "mcpServers": {
    "saylent": {
      "command": "npx",
      "args": ["-y", "saylent", "mcp"]
    }
  }
}

VS Code (GitHub Copilot agent mode)

Install in VS Code, or from a terminal:

code --add-mcp '{"name":"saylent","type":"stdio","command":"npx","args":["-y","saylent","mcp"]}'

For one workspace, .vscode/mcp.json uses a top-level servers key. An inputs entry makes VS Code prompt for a key once and store it, instead of writing it into the file:

{
  "inputs": [
    { "type": "promptString", "id": "openai-key", "description": "OpenAI API key", "password": true }
  ],
  "servers": {
    "saylent": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "saylent", "mcp"],
      "env": { "OPENAI_API_KEY": "${input:openai-key}" }
    }
  }
}

Windsurf (Devin Desktop)

Windsurf became Devin Desktop in June 2026 and keeps its MCP config under ~/.codeium/. Open the MCP settings from inside the app to edit the file it actually reads (classic Windsurf installs use ~/.codeium/windsurf/mcp_config.json), and add:

{
  "mcpServers": {
    "saylent": {
      "command": "npx",
      "args": ["-y", "saylent", "mcp"]
    }
  }
}

Codex CLI

codex mcp add saylent -- npx -y saylent mcp

or in ~/.codex/config.toml. Codex passes only a short allow-list of environment variables to a server, so name the keys you want forwarded:

[mcp_servers.saylent]
command = "npx"
args = ["-y", "saylent", "mcp"]
env_vars = ["OPENAI_API_KEY", "ANTHROPIC_API_KEY"]

Gemini CLI

gemini mcp add -s user saylent npx -y saylent mcp

or in ~/.gemini/settings.json (.gemini/settings.json for one project). Gemini CLI strips inherited variables whose name contains KEY before it starts a server, so a key has to be listed explicitly to get through:

{
  "mcpServers": {
    "saylent": {
      "command": "npx",
      "args": ["-y", "saylent", "mcp"],
      "env": { "OPENAI_API_KEY": "$OPENAI_API_KEY" }
    }
  }
}

Google replaced Gemini CLI with Antigravity CLI in June 2026. Antigravity takes the same mcpServers block in its own mcp_config.json, managed from its /mcp command.

What you say to the agent

With the Claude Code plugin, /saylent:ai-visibility-audit example.com walks the whole loop: a free estimate, your yes, the audit, the sites to get onto, the fixes with their evidence, and a verify plan. Any other client gets the same loop from a plain request, because each tool says what it costs and what it returns.

Free, ask any time:

Use saylent to gate-check example.com and tell me which AI bots are blocked.

Read the saylent report in ./example.com/2026-09-09/ and summarize the "who wins instead" section.

Use saylent sources on ./example.com/2026-09-09/run.json and list the off-site opportunities with their receipts.

Use saylent crawlers on ./logs/access.log with run_path ./example.com/2026-09-09/run.json and tell me which cited pages no AI crawler fetched.

These two spend your own provider credits: about $0.80 to $1.20 with four engines for a smoke audit (our recorded runs cost $0.93 and $1.11) and about $5.10 to $7.10 for a full one. Say the profile you want and set a ceiling:

Run a saylent smoke audit of example.com with max_usd 1, then tell me the verdict and the top three fixes.

Ship the JSON-LD fix, then run saylent verify on ./example.com/2026-09-09/run.json with max_usd 1 and tell me what moved.

A long audit narrates itself: the server streams its stages (crawl, brand model, questions, engines, judge, cited pages, site gates, fixes, score) as MCP log notifications while it runs.

On this page