transport
Streamable HTTP MCP
A stateless Model Context Protocol server at https://api.refd.ai/mcp.
agent access
Build with refd. Read your AI visibility from any agent.
refd exposes AI search monitoring for your workspaces through a remote MCP server. Connect Claude, ChatGPT, or any MCP client and query visibility, competitors, citations, and the raw answers behind them, across the workspaces you approve. Reading is the default; an optional bounded setup scope lets an agent onboard a workspace. OAuth for browser clients; personal access tokens for headless ones.
01 / the connector
Scoped to what you authorize.
At consent you pick the workspaces the connection may target: check the ones you want, use Allow all to cover every workspace on the account (including ones you create later), or provision a new workspace for the agent to onboard (the create_workspace tool needs an Allow all connection, since only those can target workspaces created after approval). Every tool takes an optional workspace selector, and the credential, never the tool arguments, defines what it may target. Personal access tokens always cover exactly one workspace. Web prompt-injection can, at worst, act inside the workspaces the human authorized: a setup-scoped agent can edit configuration, start the one onboarding report, and manage tracked prompts row by row; no grant can delete run history or manage billing, and only an administrator's connection can trigger an extra paid run (run_now). The owner can revoke the connection anytime from Settings.
auth
OAuth 2.1 + PKCE
Authorization-code flow with revocable grants. Single-workspace personal access tokens cover clients that have no browser.
scopes
Read by default
data:read: Twelve analytics tools plus a metric-glossary resource. Read-only.
data:write: Adds twelve setup tools plus revoke_connection covering the whole lifecycle: verify domains, provision a workspace, configure it, start one provider-backed onboarding report, finish onboarding, and revoke the connection when it is no longer needed. Onboarded workspaces also get row-scoped prompt management, competitor CRUD, and surface toggles (eleven tools) plus run_now, an immediate paid run limited to administrator accounts.
02 / the tools
Twelve read tools, discovered at runtime.
Call tools/list after connecting. Every tool resolves the granted workspaces from the credential; an optional workspace argument only picks among them, and get_workspace_info lists the choices.
get_workspace_info
The connected workspaces and, for the selected one: brand, tracked competitors, prompts, and enabled AI surfaces.
get_visibility_overview
Mention rate, citation rate, position, and share of voice across surfaces, with a byCohort breakdown beside the blended figure.
get_competitor_landscape
How the brand ranks against the competitors it tracks.
get_prompt_performance
Per-prompt visibility, broken down by AI surface. Each prompt carries its cohort.
get_citation_sources
Which domains AI answers cite for the workspace.
get_recent_changes
Material moves between the two most recent completed runs.
find_prompt_results
Search tracked prompts and their scored results.
read_answer
The raw AI answer behind a result, with entity mentions highlighted.
get_digest
A 30-day rollup of the workspace, the same one that grounds the dashboard chat, carrying the prompt-cohort split.
get_run_history
Recent run cycles with status, answer counts, dispatch state, and the frozen prompt count.
get_prompt_changes
A per-prompt diff of the two most recent completed runs, including zero-visibility transitions.
get_prompt_set_timeline
Every distinct prompt population the workspace has run against, and what changed between them.
get_attribute_performance
Per-capability visibility, flagging an attribute measured by a single prompt as unmeasured.
get_intent_performance
Visibility by declared funnel stage and question type. Both are declared on the prompt, never inferred, so a prompt with neither is counted as undeclared.
get_prompt_citations
The URLs cited for one prompt, with counts and an isOurs flag, in a single call.
prompt cohorts
A prompt that names the brand is scored near 1.0 by construction, so a headline that pools every prompt flatters the brand. get_visibility_overview, get_competitor_landscape, get_citation_sources, and get_prompt_performance take a kind filter, comma-separated: brand_defining (the prompt names your brand), alternative (it names only a tracked competitor), or discovery (it names neither, so the rate is unprompted visibility). Two further cohorts, problem and market_perception, are declared rather than inferred, so they appear only if someone set them. Omitting kind does not hand back a blend: get_visibility_overview, get_competitor_landscape, and get_citation_sources head their figures with the discovery cohort, because asking nothing should not return a brand-inflated number. get_visibility_overview returns headline, which names its population, beside byCohort with every cohort at once. get_digest is the exception and takes no filter: it always pools every cohort, so read sections.prompts.cohorts for one cohort on its own. list_prompts reports each prompt cohort and the counts.
setup tools · data:write
Let an agent do the setup.
With the data:write scope, the setup tools onboard a
workspace end to end: get_setup_state, check_domain on every candidate domain, set_brand, draft_description, suggest or update competitors and prompts (prompt generation is steerable by count and theme), preview_setup, explicit user approval, confirm_setup, then get_setup_report until the runs land, then complete_setup to finish. When the connection is no longer wanted, revoke_connection ends the access it had. The workflow is
budgeted, and confirm_setup starts exactly one
provider-backed onboarding report. Past onboarding, prompt changes
stay operational; only an administrator's connection can trigger an
extra paid run. No grant can delete run history or manage billing.
create_workspace
Provisions a new workspace for the connection. Needs an Allow all connection: a checked grant could never target a workspace created after approval.
check_domain
Verifies a domain resolves and where its redirect chain lands. Run it before saving any brand or competitor domain: a wrong domain silently breaks citation matching forever.
get_setup_state
The setup wizard state: phase, editable draft, version, regeneration allowances, plus the effective limits and the generation budget of the last 24h.
set_brand
Sets or updates the tracked brand: name, domains, aliases.
draft_description
Fetches the brand website and drafts description, summary, and target market.
suggest_competitors
Generates editable competitor candidates from indexed company search; failures carry the cause and the raw candidate domains they saw.
suggest_prompts
Generates categorized, editable buyer-question candidates, steerable by count and theme.
update_setup
Applies explicit edits to any draft field, including enabled surfaces.
preview_setup
Returns the exact canonical configuration, its hash, and a per-surface expected-check breakdown.
confirm_setup
Commits the approved configuration and starts the one provider-backed onboarding report.
get_setup_report
Live progress and the pinned setup report for the run group.
complete_setup
Marks the workspace onboarded after the commit, the same gate the dashboard "enter dashboard" click passes.
revoke_connection
Revokes this connection: the grant, every token under it, and access to every approved workspace die together, after an explicit confirm argument. Only ever touches the connection the credential belongs to.
prompt tools · data:write
Keep an onboarded workspace current.
Row-scoped prompt management: a single prompt changes without rewriting the setup draft. list_prompts to resolve ids, add_prompt / update_prompt / toggle_prompt / remove_prompt for row-scoped changes (no setup draft, no list rewrite; in-flight runs keep their frozen prompt set), then run_now when the next scheduled run is too far away and get_prompt_performance with range 1d to check the results. A new prompt is classified into a cohort from its text; add_prompt and update_prompt take an optional kind to override that, and the resolved cohort comes back in the response.
list_prompts
Every tracked prompt with id, text, category, tags, active status, and answer counts, plus the active-prompt limit and the valid categories.
add_prompt
Adds one prompt (optional category becomes its single tag) and returns the assigned id; a repeated text converges to the existing prompt.
update_prompt
Rewords the text and/or changes the category of one prompt; text is unique per workspace.
toggle_prompt
Enables or disables a prompt while keeping its history; activation respects the active-prompt ceiling.
remove_prompt
Retires a prompt that has results (history preserved, re-activatable) and deletes one that has none.
run_now
Triggers an immediate paid collection run over the current active prompt set; administrator accounts only, at most 5 per hour per workspace.
tracking tools · data:write
Competitors and surfaces, without the dashboard.
Brand edits stay in set_brand, which applies immediately to the live brand entity.
add_competitor
Adds one tracked competitor: unique name, verified domains, and optional aliases; returns the assigned id.
remove_competitor
Removes a competitor by name; refused when scored results would be destroyed.
list_competitors
The tracked competitors with id, name, domains, and aliases.
enable_surface
Turns on one AI surface for the next run; respects the surface ceiling.
disable_surface
Turns one AI surface off; the last surface cannot be disabled.
03 / connect
Point a client at the endpoint.
The endpoint is always https://api.refd.ai/mcp. Discovery and sign-in are automatic; you approve the workspaces a connection covers.
Claude / Claude Code
Add a custom connector (or `claude mcp add --transport http refd https://api.refd.ai/mcp`) and complete the OAuth sign-in.
ChatGPT
Settings → Connectors → add a custom MCP server, enter the endpoint, and authorize.
Any MCP client
Point a Streamable HTTP MCP client at the endpoint; it discovers auth via the protected-resource metadata. opencode-style configs take `{ "mcp": { "refd": { "type": "remote", "url": "...", "headers": { "Authorization": "Bearer refd_..." } } } }`.
one-click install
Claude Code
claude mcp add-json refd '{"type":"http","url":"https://api.refd.ai/mcp"}' Then run `claude mcp login refd` to complete the OAuth sign-in.
VS Code CLI
code --add-mcp '{"name":"refd","type":"http","url":"https://api.refd.ai/mcp"}' Adds the server to the user profile; approve the sign-in when prompted.
04 / headless and CI agents
No browser? Use a personal access token.
OAuth needs a browser. For CI, cron, servers, and sandboxed agents, Settings → Personal access tokens issues a workspace-scoped, read-only bearer token. It is shown once and stored only as a hash.
create
Name it after the agent
Generate the token in Settings, scoped to the current workspace. The prefix shown in the dashboard tells tokens apart.
authenticate
Bearer on every request
The token authenticates exactly like an OAuth grant, rate-limited per token, and revoking it in Settings takes effect on the next request.
smoke test
curl -X POST https://api.refd.ai/mcp \
-H "Authorization: Bearer refd_..." \
-H 'Content-Type: application/json' \
--data '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"ci","version":"1"}}}' 05 / discovery
Everything is discoverable.
MCP endpoint
https://api.refd.ai/mcp
Streamable HTTP, OAuth-protected
Protected-resource metadata
https://api.refd.ai/.well-known/oauth-protected-resource/mcp
RFC 9728
Authorization-server metadata
https://api.refd.ai/.well-known/oauth-authorization-server
RFC 8414
OpenAPI catalog
https://refd.ai/openapi.json
Public HTTP surface
Agent manifest
https://refd.ai/.well-known/agent
Discovery pointers
MCP Registry
ai.refd/refd
registry.modelcontextprotocol.io
Agent skill
https://refd.ai/skills/refd/SKILL.md
Installable SKILL.md
Prompt set design skill
https://refd.ai/skills/ai-prompt-set-design/SKILL.md
Installable SKILL.md, tool-neutral
llms.txt
https://refd.ai/llms.txt
Plain-text summary
06 / trust and source
Inspect the boundary, or self-host the stack.
refd is MIT licensed and runs on Cloudflare Workers. The open-source guide explains the architecture and self-hosted boundary. Hosted access is covered by the security overview, privacy policy, and terms of service. Connection help lives on the support page.