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.
- Claude.ai: Settings, Connectors, Add custom connector. Name it Insight Engine and paste
https://insightengine.studio/api/mcp. Choose Connect, sign in, approve. - 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
| Tool | What it does | Cost |
|---|---|---|
list_sites | Your sites, each with its id, domain, latest AI Visibility Score and when it was last checked. | Free |
get_score | A 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_answers | What each AI assistant says about the business, the questions asked and which competitors were named instead. | Free |
get_fixes | What to fix: fix checks, next moves ranked by effect and effort, and fixes already generated. | Free |
get_usage | This month's checks and generated fixes used against your plan. | Free |
run_check | Queues 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_run | A queued check's status and, once finished, the new score and the score per assistant. | Free |
get_latest_report | The newest monthly report for a site as data and markdown, with a PDF link anyone can open for 24 hours. | Free |
generate_report | Builds the monthly report now from the latest stored checks and keeps it. | No allowance used (30 a day at most) |
generate_fix | Writes 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_..."| Method | Path | Scope | What it does |
|---|---|---|---|
| GET | /sites | sites:read | List sites |
| GET | /usage | sites:read | This month's usage |
| GET | /sites/{site}/score | scores:read | AI Visibility and Search scores |
| GET | /sites/{site}/answers | answers:read | What each assistant says (optional ?engine=) |
| GET | /sites/{site}/fixes | fixes:read | Fix checks, next moves, generated fixes |
| POST | /sites/{site}/fixes | fixes:write | Generate a fix (returns 201) |
| POST | /sites/{site}/checks | checks:write | Queue a check (returns 202 with a runId) |
| GET | /runs/{runId} | scores:read | Check status and score |
| POST | /sites/{site}/reports | reports:write | Build a report now (returns 201) |
| GET | /sites/{site}/reports/latest | reports:read | Newest report for a site |
| GET | /reports/{id} | reports:read | One report as JSON |
| GET | /reports/{id}/pdf | reports:read | Report 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.
| Scope | Allows | Cost |
|---|---|---|
sites:read | List your sites and usage | Free |
scores:read | Read AI Visibility and Search scores | Free |
answers:read | Read what each AI assistant says about you | Free |
fixes:read | Read fix checks, next moves and generated fixes | Free |
reports:read | Read reports | Free |
reports:write | Create reports | No AI cost; limited to 30 a day. |
checks:write | Run AI visibility checks | Counts against this month's checks on your plan. |
fixes:write | Generate fixes | Counts 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.
| Code | HTTP | Meaning |
|---|---|---|
unauthorized | 401 | Missing, wrong, revoked or expired API key. |
paid_required | 402 | The API needs a paid plan. `upgrade` links to billing. |
plan_cap | 402 | This 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`.) |
scope | 403 | The key lacks the scope this endpoint needs. |
not_found | 404 | No such site, run or report on this account (also used when it belongs to another account). |
invalid_request | 400 | The request is malformed; `issues` lists what is wrong. |
rate_limited | 429 | Slow down; wait `Retry-After` seconds. |
server_error | 500 | Our 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