MCP technical details

Protocol-level reference for anyone integrating directly. If you only want to use Subsig through Claude, Agents and MCPs covers everything you need.

Auth & requests

Two auth paths

Every response carries

Multi-workspace accounts

A key has one anchor workspace, used when organisation_uuid is omitted, plus an explicit list of others it can reach. Call list_workspaces to get the full list, then pass organisation_uuid on any other tool to target a specific one.

Dates and providers

Every date_from and date_to pair is an absolute calendar date in YYYY-MM-DD, never a relative shorthand, and read as a plain day on the server’s own clock — not UTC, not the caller’s timezone. Left out, most tools default to the last 30 days. Provider values are openai, perplexity, and google_ai_overviews.

Plan limits

The MCP server has no entitlement system of its own. It forwards your organisation’s own API key on every backend call, so these come straight from your plan.

Requests per minute and records per call are the general Public API entitlement, shared with any other integration on the same key. The monthly MCP figure sits on top of that, resets on the 1st of the calendar month, and applies to MCP tool calls only.

Tools: full request/response reference

13 tools over one backend surface. Every example below is a real captured response, not hand-written. All 13 are read-only.

list_workspaces

Lists the workspaces this key can access, flagging which is primary.

{
  "workspaces": [
    { "uuid": "f5860bb7-...", "name": "Acme Notes", "is_primary": true }
  ]
}

list_ai_visibility_topics

Topics prompts are grouped under, with active prompt counts.

{
  "topics": [
    { "id": 1, "name": "Pricing questions", "description": "Prompts about pricing and plans", "active_prompt_count": 1 }
  ]
}

list_ai_visibility_prompts

Tracked prompts, optionally filtered to one topic.

{
  "prompts": [
    { "id": 1, "text": "What is the best note-taking app for teams?", "topic_id": 1,
      "country": "US", "language": "en", "frequency": "daily", "status": "active",
      "providers": ["openai", "perplexity"] }
  ]
}

get_ai_visibility_prompt_detail

One prompt’s visibility, share of voice, and recent AI answers.

{
  "prompt": {
    "id": 1, "text": "What is the best note-taking app for teams?",
    "brand_name": "Acme Notes", "visibility_pct": 52, "sov_pct": 65, "avg_position": 2.1,
    "recent_responses": [
      { "provider": "perplexity", "model": "sonar", "answer": "Acme Notes and Rival Notes are both popular choices for team note-taking.", "scheduled_at": "2026-09-03 15:20:48" }
    ]
  }
}

list_ai_visibility_brands

Every tracked brand, own and competitors, ranked by AI visibility.

{
  "brands": [
    { "name": "Acme Notes", "is_own_brand": true, "rank": 1, "visibility_pct": 52, "sov_pct": 65, "avg_position": 2.1 },
    { "name": "Rival Notes", "is_own_brand": false, "rank": 2, "visibility_pct": 28, "sov_pct": 35, "avg_position": 2.4 }
  ]
}

get_ai_visibility_overview

The account-level snapshot: your score, rank, and top competitors.

{
  "overview": {
    "visibility_pct": 58.9, "sov_pct": 28.7, "avg_position": 2.7, "brand_rank": 1,
    "competitors": [
      { "name": "GitHub", "website": "github.com", "visibility_pct": 41.4, "sov_pct": 20.2, "avg_position": 2.1 },
      { "name": "Linear", "website": "linear.app", "visibility_pct": 28.4, "sov_pct": 13.9, "avg_position": 4.2 }
    ],
    "date_from": "2026-08-05", "date_to": null
  }
}

Live capture from the jira workspace, September 2026.

get_ai_visibility_brand_detail

Deep dive on one named brand, usually a competitor.

{
  "brand": {
    "name": "GitHub", "website": "github.com", "is_own_brand": false, "rank": 2,
    "visibility_pct": 41.4, "sov_pct": 20.2, "avg_position": 2.1, "date_from": "2026-08-05", "date_to": null
  }
}

get_ai_visibility_sentiment

Positive, neutral, and negative split when a brand is mentioned.

{
  "sentiment": { "name": "Acme Notes", "positive_count": 6, "neutral_count": 3, "negative_count": 1, "sentiment_score": 0.72, "date_from": "2026-08-04", "date_to": null }
}

get_ai_visibility_platforms

Visibility broken out by AI provider.

{
  "platforms": {
    "name": "Acme Notes",
    "platforms": [
      { "provider": "openai", "visibility_pct": 46.7 },
      { "provider": "perplexity", "visibility_pct": 40 }
    ],
    "date_from": "2026-08-04", "date_to": null
  }
}

get_ai_visibility_citations

Which domains and URLs AI answers cite when they mention a brand.

{
  "citations": {
    "name": "GitHub",
    "my_domain_contribution_pct": null, "my_url_contribution_pct": null,
    "top_domains": [
      { "domain": "atlassian.com", "classification": "corporate", "citation_count": 129 },
      { "domain": "reddit.com", "classification": "ugc", "citation_count": 98 }
    ],
    "top_urls": [
      { "url": "https://monday.com/blog/rnd/bug-tracking-software/", "classification": "other", "citation_count": 31 }
    ]
  }
}

The two contribution percentages only populate on the org-wide view, meaning a call with no name. Passing a specific brand name returns null for both. Real behavior, not a bug.

get_ai_visibility_status

Whether today’s visibility checks have finished running yet.

{
  "status": { "ready": true, "in_progress": false, "executions_total": 100, "executions_completed": 96, "visibility_pct": 20.4 }
}

list_agent_reports

Already-generated agent reports: Root Cause Analysis, Prompts Discovery, Competitive Benchmark, AI Visibility Roadmap.

{
  "reports": [
    { "id": 126, "agent_type": "root_cause_analysis", "focus_topic": "Citations from usepylon.com dropped by 6 in the last week", "status": "completed", "created_at": "2026-08-20T15:50:16.000000Z" }
  ]
}

get_agent_report

The full findings from one already-generated report, plus a signed download URL for its PDF or DOCX file if it has finished rendering.

{
  "report": {
    "id": 1, "agent_type": "competitive_benchmark", "status": "completed",
    "result": { "summary": "Acme Notes leads Rival Notes on 2 of 3 tracked prompts this period." },
    "error_message": null, "pdf_url": null, "docx_url": null
  }
}

pdf_url and docx_url are signed, 24-hour links, populated once an export exists for that report. Both are real fields, just null when no export was generated.

Errors

Every response, success or failure, is real JSON. Never a silent empty result on a genuine problem.

No data yet, versus not tracked

A tracked brand with zero checks so far still returns 200 with zeroed counts and empty arrays, never an error. A brand that was never registered as an AI Visibility competitor returns 404 brand_not_tracked_by_ai_visibility instead. The two are kept distinct on purpose, so a quiet brand never looks identical to one that was never set up.

Scope & limits

• Can’t create, edit, pause, or delete tracked prompts, competitors, or topics. Every tool is read-only.

• Can’t trigger a new agent report; it only reads reports already generated from the dashboard.

• Can’t change plan, billing, seats, or workspace settings.

• Can’t look back further than the plan’s history entitlement, even if asked to.

• Connects fine on Free, but every AI Visibility and report call is blocked. Free’s MCP quota is zero.

💡 Include the request_id from a failed response when you contact support. It points at the exact call in our logs.