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 and start the one onboarding report, and no grant can delete data, manage billing, or start further runs. 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: Nine 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.
02 / the tools
Nine 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.
get_competitor_landscape
How the brand ranks against the competitors it tracks.
get_prompt_performance
Per-prompt visibility, broken down by AI surface.
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.
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; no grant can delete data,
manage billing, or start further runs.
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.
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
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.