MCP Server

The SurfacedBy MCP server lets an MCP-compatible AI tool, such as Claude, ChatGPT, Codex, Cursor, or VS Code, read your AI visibility data: scores, citations, competitors, opportunities, plan status, reports, and more. You can then ask questions about your AI visibility without leaving the tool you already work in.

Plans

• Starter, Professional, and Agency plans, and the free trial: read tools.
• Agency plan: management tools and draft tools can additionally be granted to a connection (see below).

Plan requirements are checked when a connection is created or edited and again on every tool call, so a connection stops working for tools your plan no longer includes.

Creating a connection

Workspace owners and admins manage connections under Settings > Integrations > AI clients (MCP). Creating a connection takes two steps:

1. Configure. Name the connection, choose whether it can read every brand in the workspace or only selected brands, choose its scopes, and set when it expires (90 days, 6 months, or 12 months). Workspace overview, Brand basics, Visibility analytics, and Opportunities are on by default, and you can turn on any other scope your workspace qualifies for. Content projects, Engagement, and Outreach scopes need those features to be live for the workspace; management and draft scopes need the Agency plan.
2. Connect. SurfacedBy creates the connection and shows its API key once. Copy it then; it cannot be shown again.

A connection belongs to one workspace. A workspace can have up to 20 active connections. Admins can edit a connection's name, scopes, and brands, and can revoke it at any time, after which its key stops working. To extend a connection past its expiry, create a new one.

Connecting your AI tool

The server endpoint is:

https://api.surfacedby.com/api/v1/mcp/

Keep the trailing slash. The server uses the Streamable HTTP transport and authenticates with the connection's API key, sent in the X-API-Key header. There is no OAuth sign-in. The Connect step shows the exact setup for each client:

• Claude Code:

  claude mcp add --transport http surfacedby https://api.surfacedby.com/api/v1/mcp/ --header "X-API-Key: YOUR_KEY"

• Cursor and VS Code (mcp.json):

  {
    "mcpServers": {
      "surfacedby": {
        "url": "https://api.surfacedby.com/api/v1/mcp/",
        "headers": { "X-API-Key": "YOUR_KEY" }
      }
    }
  }

• Claude.ai, Claude Desktop, and ChatGPT connectors accept only a URL, so the key goes in the URL as ?api_key=YOUR_KEY. Add a custom connector, paste that URL, and leave the authentication or OAuth fields empty. Treat that URL like a password.

• Any other client can connect through the mcp-remote bridge: npx mcp-remote https://api.surfacedby.com/api/v1/mcp/ --header "X-API-Key: YOUR_KEY".

The key is the credential. Store it like any other secret, and revoke the connection if it leaks.

What a connection can do

Start with surfacedby_list_capabilities: it lists every tool, grouped by category, and shows which ones this connection can use and which need a scope, feature, or plan it does not have.

Read tools

Content projects, Engagement, and Outreach tools work only when that feature is available to the workspace. Engagement tools include suggested reply text only if you tick the option to share it when you configure the connection. Opportunity tools return evidence in summary form; the full evidence detail stays in the dashboard.

The AI-referral traffic tool includes the 24-hour, 7-day and 30-day referral/conversion summaries, plus anonymous traffic measurement for each window: lower-bound AI visit and agent-load shares, their numerators and denominators, verified crawler requests, excluded identity observations, and collector coverage. It keeps unavailable and insufficient-sample states instead of replacing them with a zero percentage. Session counts are not used as share denominators, and individual visits, request paths and credentials are not included.

Each window also includes topic totals from the shared Tracking reader: linked-page demand, current-check citation share, measurement date, and link coverage. Unmeasured topics keep an unavailable value. Topic totals can overlap and must not be summed as site traffic. Individual prompts and linked page paths stay in the dashboard; the tool reports exact totals when a topic list is truncated.

Conversion amounts retain their reported currency. Each window and engine includes a per-currency revenue list; a mixed or unknown unit has no combined value. Unknown amounts keep a currency of null, and a mixed revenue trend stays unavailable. Engine conversion totals combine hostname aliases before display limits; the remaining counts and amounts appear in Other AI.

Management tools (Agency plan)

These make reversible changes and use no credits:

• surfacedby_manage_prompt - accept or dismiss an AI prompt suggestion, or pin or unpin a tracked prompt.
• surfacedby_manage_competitor - track a competitor by its domain, or stop tracking one.
• surfacedby_manage_opportunity - add an opportunity to the brand's plan, or dismiss it.

Draft tools (Agency plan)

These generate drafts for you to review, and each needs the matching feature (engagement, content, or outreach) to be live for the workspace. Each works in two steps: a preview tool estimates the credits and returns a confirmation token, and the generate tool runs only with that token. Generation uses your workspace's credits, and nothing is published or sent.

• surfacedby_preview_engagement_draft, then surfacedby_generate_engagement_draft - a reply draft for a community conversation.
• surfacedby_preview_content_draft, then surfacedby_start_content_draft - creates a content project from an opportunity and generates its brief. You generate the full draft in the dashboard.
• surfacedby_preview_outreach_pitch, then surfacedby_generate_outreach_pitch - a pitch draft for a confirmed outreach target.

Every write also checks the role of the admin who created the connection, so a connection loses write access if that person's role is lowered.

What a connection never does

Whatever you grant, a connection cannot post, publish, or send anything externally, trigger a check, write the prompts your brand is checked against, edit or delete existing plan items, or read data outside its workspace and brands. Credits are spent only by the draft tools, and only after a preview and confirmation.

Limits

Each connection can make up to 120 requests per minute and 100,000 per month, with further per-workspace and per-IP limits. A request over a limit returns HTTP 429.

Monitoring use

The AI clients (MCP) settings page shows active connections, tool calls and errors today, and the time of the last call, plus a log of individual tool calls with the outcome, the scope used, the brands in scope, the duration, and the response size.

What you can ask

Once connected, you can ask your AI tool questions such as:

• "What is my Visibility Score and how did it move on my main domain?"
• "Which competitors are picking up citations I am missing?"
• "What are my top opportunities right now?"
• "Summarize the latest report for this brand."

The AI tool answers from your SurfacedBy data.