# Build with refd: agent access

> Connect an AI agent to refd's MCP server. Read AI search visibility, competitors, citations, and answer evidence, or let an agent set up a workspace, across the workspaces you choose.

Canonical URL: https://refd.ai/agents

refd exposes AI search monitoring for your workspaces through a remote MCP server at `https://api.refd.ai/mcp`. Connect Claude, ChatGPT, or any Model Context Protocol client and query visibility, competitors, citations, and the raw answers behind them. Reading is the default; an optional bounded setup scope lets an agent onboard a workspace.

## The connector

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.

- Transport: stateless Streamable HTTP MCP at `https://api.refd.ai/mcp`.
- Auth: OAuth 2.1 authorization code with PKCE and revocable grants. Personal access tokens (single-workspace) cover clients that have no browser.
- Scope `data:read`: Nine analytics tools plus a metric-glossary resource. Read-only.
- Scope `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.

## Read tools

- `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.

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.

## Setup tools (data:write)

- `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.

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.

## Connect a client

- 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_..." } } } }`.

## Install in one click

- Cursor: [open the installer](cursor://anysphere.cursor-deeplink/mcp/install?name=refd&config=eyJ0eXBlIjoiaHR0cCIsInVybCI6Imh0dHBzOi8vYXBpLnJlZmQuYWkvbWNwIn0=) (Cursor opens, adds the server, and starts the OAuth sign-in.)
- VS Code: [open the installer](vscode:mcp/install?name=refd&config=%7B%22type%22%3A%22http%22%2C%22url%22%3A%22https%3A%2F%2Fapi.refd.ai%2Fmcp%22%7D) (VS Code opens, adds the server, and starts the OAuth sign-in.)
- 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.)

## Headless and CI agents

OAuth needs a browser. Where there is none (CI, cron, servers, sandboxed agents), create a workspace-scoped read-only personal access token:

- No workspace yet? Create an account (business email) at https://dash.refd.ai/auth/create-account and finish the onboarding wizard. Self-hosted: register on your own dashboard.
- Open the workspace, go to Settings → Personal access tokens, and create a token named after the agent or pipeline.
- Copy the token once. It is stored only as a SHA-256 hash and cannot be retrieved again.
- Send it as `Authorization: Bearer refd_...` on every MCP request. It authenticates exactly like an OAuth grant: read-only, scoped to the one workspace, rate-limited per token, revoked from Settings.

```bash
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"}}}'
```

## Discovery

- 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)

## Trust and source

refd is MIT licensed and runs on Cloudflare Workers. The [open-source guide](https://refd.ai/open-source.md) explains the architecture and the self-hosted boundary. Hosted access is covered by the [security overview](https://refd.ai/security.md), [privacy policy](https://refd.ai/privacy.md), and [terms of service](https://refd.ai/terms.md). Connection help lives on the [support page](https://refd.ai/support.md).