MCP server and API

Let your AI agent read your visibility

Connect Claude, ChatGPT, Cursor or your own app to Insight Engine. Ask what AI assistants say about your business, run a check, pull a report or generate a fix, without opening the dashboard.

The MCP server and API are included on every paid plan. See pricing. Free accounts and free trials can't connect.

The MCP server

MCP (Model Context Protocol) is how AI assistants use outside tools. Insight Engine runs an MCP server, so an assistant you already use can look up your scores and act on them, with your say-so. Reading is free. Running a check or generating a fix uses this month's allowance on your plan, and only when the connection has permission to do it.

https://insightengine.studio/api/mcp

It speaks streamable HTTP. Sign in with Google and approve (OAuth), or send an API key as a bearer token.

Connect

Claude.ai and ChatGPT

No key needed. You sign in with the Google account you use for Insight Engine and approve the connection.

  1. Claude.ai: Settings, Connectors, Add custom connector. Name it Insight Engine and paste https://insightengine.studio/api/mcp. Choose Connect, sign in, approve.
  2. ChatGPT: Settings, Apps and Connectors, create a connector (developer mode, under Advanced). Paste the URL, choose OAuth, sign in, approve.

Claude Code

claude mcp add --transport http insight-engine https://insightengine.studio/api/mcp

Then type /mcp in Claude Code and choose Insight Engine to sign in. Or use a key, for scripts and shared machines:

claude mcp add --transport http insight-engine https://insightengine.studio/api/mcp --header "Authorization: Bearer <key>"

Cursor, in ~/.cursor/mcp.json

{
  "mcpServers": {
    "insight-engine": {
      "url": "https://insightengine.studio/api/mcp",
      "headers": {
        "Authorization": "Bearer <key>"
      }
    }
  }
}

VS Code, in .vscode/mcp.json

{
  "servers": {
    "insight-engine": {
      "type": "http",
      "url": "https://insightengine.studio/api/mcp",
      "headers": {
        "Authorization": "Bearer <key>"
      }
    }
  }
}

Create keys under Connect in your dashboard. A key can be limited to some scopes and to some sites, so a client's app only sees that client's site. Connected apps and keys can be revoked there at any time.

The 10 tools

ToolWhat it doesCost
list_sitesYour sites, each with its id, domain, latest AI Visibility Score and when it was last checked.Free
get_scoreA site's AI Visibility Score with its parts, score per AI assistant, history, site health and the Search score when Search Console is connected.Free
get_ai_answersWhat each AI assistant says about the business, the questions asked and which competitors were named instead.Free
get_fixesWhat to fix: fix checks, next moves ranked by effect and effort, and fixes already generated.Free
get_usageThis month's checks and generated fixes used against your plan.Free
run_checkQueues a fresh check across the AI assistants on your plan. Takes one to two minutes.One of this month's checks (6 a day at most)
get_runA queued check's status and, once finished, the new score and the score per assistant.Free
get_latest_reportThe newest monthly report for a site as data and markdown, with a PDF link anyone can open for 24 hours.Free
generate_reportBuilds the monthly report now from the latest stored checks and keeps it.No allowance used (30 a day at most)
generate_fixWrites title and meta rewrites, or a content brief, for a site.One of this month's generated fixes, even if generation fails

Most tools take a site: a site id from list_sites or its domain, like example.com. What the AI assistants wrote about you comes back as quoted third-party text, marked as such, so your agent treats it as information and not as instructions.

REST API

The same service, as JSON over HTTPS, for scripts and your own apps. Base URL https://insightengine.studio/api/v1. Send an API key as a bearer token.

curl https://insightengine.studio/api/v1/sites \
  -H "Authorization: Bearer ie_live_..."
# queue a check, then poll it
curl -X POST https://insightengine.studio/api/v1/sites/example.com/checks \
  -H "Authorization: Bearer ie_live_..." \
  -H "Content-Type: application/json" -d '{}'

curl https://insightengine.studio/api/v1/runs/<runId> \
  -H "Authorization: Bearer ie_live_..."
MethodPathScopeWhat it does
GET/sitessites:readList sites
GET/usagesites:readThis month's usage
GET/sites/{site}/scorescores:readAI Visibility and Search scores
GET/sites/{site}/answersanswers:readWhat each assistant says (optional ?engine=)
GET/sites/{site}/fixesfixes:readFix checks, next moves, generated fixes
POST/sites/{site}/fixesfixes:writeGenerate a fix (returns 201)
POST/sites/{site}/checkschecks:writeQueue a check (returns 202 with a runId)
GET/runs/{runId}scores:readCheck status and score
POST/sites/{site}/reportsreports:writeBuild a report now (returns 201)
GET/sites/{site}/reports/latestreports:readNewest report for a site
GET/reports/{id}reports:readOne report as JSON
GET/reports/{id}/pdfreports:readReport PDF (key, or the signed link in the report)

Machine readable: /api/v1/openapi.json (OpenAPI 3.1). Ids are UUIDs, timestamps are ISO 8601. OAuth tokens issued for the MCP server aren't accepted on the REST API; use a key.

Scopes

Every key and every connection carries scopes. A call without the scope it needs is refused with scope and costs nothing.

ScopeAllowsCost
sites:readList your sites and usageFree
scores:readRead AI Visibility and Search scoresFree
answers:readRead what each AI assistant says about youFree
fixes:readRead fix checks, next moves and generated fixesFree
reports:readRead reportsFree
reports:writeCreate reportsNo AI cost; limited to 30 a day.
checks:writeRun AI visibility checksCounts against this month's checks on your plan.
fixes:writeGenerate fixesCounts against this month's generated fixes on your plan.

Rate limits

  • 120 requests a minute per key or connection, and 600 a minute per account.
  • MCP protocol messages (listing tools and so on) have their own allowance of 300 a minute per connection; tool calls also count above.
  • An address that sends more than 1200 requests a minute is refused with a 429 before its key is even checked.
  • 6 AI visibility checks a day per account, shared with the dashboard's Re-check button.
  • 30 generated reports a day per account.

When you're over, you get 429 with a Retry-After header in seconds. X-RateLimit-Remaining on each successful response says how many requests are left this minute.

Errors

Every refusal is JSON an agent can read: { "error": "...", "code": "...", "upgrade": "https://..." }. upgrade is only present when upgrading or adding capacity would fix it. MCP tools return the same JSON with isError: true.

CodeHTTPMeaning
unauthorized401Missing, wrong, revoked or expired API key.
paid_required402The API needs a paid plan. `upgrade` links to billing.
plan_cap402This month's generated fixes on the plan are used up. (Checks report a used-up plan or a paused budget as run status `refused`, with the reason in `error`.)
scope403The key lacks the scope this endpoint needs.
not_found404No such site, run or report on this account (also used when it belongs to another account).
invalid_request400The request is malformed; `issues` lists what is wrong.
rate_limited429Slow down; wait `Retry-After` seconds.
server_error500Our side failed; retry shortly.

Questions or a use we don't cover yet? Tell us.

See where you stand with AI and Google

Sign in with Google, add your website, and get your AI Visibility Score in about a minute. Free plan, no card needed.

Paid plans add all five assistants every week. See pricing

built by 920four