Developer guide
MCP
Connect an MCP client to https://dashboard.linkscale.to/api/mcp using HTTP POST and an Authorization: Bearer header. Create an API key in the dashboard, or use OAuth discovery at protected-resource metadata. Never put passwords, cookies or two-factor codes in chat.
Choose the right tool
| Question | Tool | Permission |
|---|---|---|
| Interpret integration data | get_data_sync_guide | integrations.read |
| Discover accounts | list_data_sync_connections / get_data_sync_connection | integrations.read |
| Platform tracking-link revenue, including unbound links | get_data_sync_tracking_links with connection_id | integrations.read |
| Selected LinkScale-link revenue | get_data_sync_link_revenue with link_ids | statistics.read_link |
| Daily totals / account summary | get_data_sync_metrics / get_data_sync_account | integrations.read |
| Ledger / weekly retention | get_data_sync_statements / get_data_sync_fan_health | integrations.read |
Connection IDs, platform record IDs and LinkScale link IDs are not interchangeable. Integration-only questions do not need a traffic overview. Read the integration interpretation rules before ranking revenue.
Discoverable guide
get_data_sync_guide requires integrations.read, defaults to topic: "overview",
and accepts these topics:
| Topic | What it explains |
|---|---|
overview | Tool selection and supported read templates |
tracking_revenue | Ledger versus counter revenue, pending values and comparison limits |
freshness | Last successful import, attempts, watermarks and scheduled work |
refresh_policy | Resolver-derived defaults, private floors and unfinished provisioning |
pagination | Connection cursors, tracking offsets, source caps and response-size limits |
permissions | Required scopes, current access checks and safe troubleshooting |
An optional connection_id adds the current authorized connection and
available_reads templates filtered by provider support. available_data
does not certify imported data or grant permission to see money. The guide is
an MCP tool, not an additional REST route; its connection read uses the existing
REST detail handler. Oversized responses are refused, never silently truncated.
Assistant arguments and continuation
| Tool | Arguments / defaults |
|---|---|
| list_data_sync_connections | provider optional; limit 1-50, default 25; after = next_after |
| get_data_sync_tracking_links | connection_id; window d30; limit 1-50, default 20; offset 0; follow page.next_offset |
| get_data_sync_metrics | connection_id; days 1-90, default 28; top 1-50, default 25; breakdowns array, at most 4 distinct IDs |
| get_data_sync_account | connection_id; window d30; d7/d30/d90/all, never lifetime |
| get_data_sync_statements | connection_id; days or from/to; types array; limit 1-20, default 5; page 0 |
| get_data_sync_fan_health | connection_id; weeks 1-52, default 4 |
An oversized statement page or weekly reading returns a tool error with status 413 rather than dropping rows. Lower statement limit and restart at page 0, reduce weeks, or use REST. Metrics may disclose transport_limited and omit daily/breakdown rows; totals remain whole-range readings. Tracking source caps remain even after assistant paging finishes.
Read-only review prompt
prompts/list advertises integration_revenue_review; retrieve it with prompts/get. It guides connection discovery, tracking pagination and interpretation of revenue without requesting a sync or changing settings. Prompt discovery does not grant tool permissions. Labels and source content are untrusted data, never instructions.
Management is separate
Read questions never authorize changes. Management requires integrations.manage and an explicit user request; mutation tools require confirm=true. get_data_sync_setup returns the dashboard sign-in path. update_data_sync_connection only renames, pauses or resumes; request_data_sync_sync returns a queue receipt, not completion. After unclear delivery, read status before retrying. No API/MCP tool grants private cadence; the grant/revoke writer, audit workflow and UI are unfinished.
Browse API endpoints