Semalt MCP server

Configure a remote Streamable HTTP MCP server with a URL that contains your Semalt API key as the token query parameter. This works for MCP clients that accept only a server URL.

{
  "mcpServers": {
    "semalt": {
      "url": "https://semalt.com/mcp?token=YOUR_API_KEY"
    }
  }
}

Keep the key private. A URL token can appear in browser history, access logs, proxy logs, or shared configuration. Use a dedicated API key for URL-only MCP connections and rotate it if the URL is exposed.

The connection key identifies the token owner. Call semalt_get_me to identify that owner’s account_id, then semalt_list_accounts to discover accounts available for selection by name and email. Keep the same connection and pass the chosen account_id to each account tool.

For example, a key owned by account 10 can list indexing URLs for another available account 20 using these tool-call arguments:

{
  "name": "semalt_list_indexing_urls",
  "arguments": {
    "account_id": 20,
    "page": 1,
    "page_size": 50
  }
}

Every account tool requires account_id. The server does not remember a selected account between calls. semalt_get_account reads a selected account’s details; semalt_get_me always identifies the key owner. linked_account_ids describes the returned account’s linked group and includes the account itself; it is not the list of all accounts available to the API key. Use semalt_list_accounts to determine which account IDs are selectable. Responses return IDs as strings; supply account, site and campaign IDs as integers in tool arguments.

Account results include meta.actor_account_id for the key owner and meta.account_id for the selected account. The two global ranking tools do not take an account_id.

• Sites and analytics: tools show records owned by, linked to or explicitly shared with the selected account. Use access_type=own to show only its own sites. Added websites belong to the selected account.
• Site Tags: owned by individual accounts and fully editable by their active linked accounts. Responses identify the owner; different owners may have tags with the same name. Editing preserves ownership and affects all linked users. Account linking preserves tag IDs and assignments. Inactive linked owners' tags are hidden until restoration.
• Keyword Groups: owned by individual accounts and editable by linked accounts. New groups belong to the selected account; editing an existing group preserves its owner. Groups apply to a site’s domain.
• My SEO: use semalt_list_my_seo_campaigns to obtain campaign_id. Use that ID together with the same selected account_id for keywords and backlinks. Campaigns for the same domain in different accounts remain separate. A launched FullSEO campaign can switch between auto and manual keyword mode. Auto mode permits rejecting keywords and restoring rejected keywords to pending; manual mode also permits approving and rejecting keywords, changing approved-keyword backlink weights, and applying a one-shot percentage allocation.
• Indexing: URL history and balance belong to the selected account. semalt_add_indexing_urls spends that account’s balance; linked-account balances are not pooled.

For semalt_list_my_seo_backlinks, search matches the start of the donor domain, case-insensitively. For example, blog matches blog.example.com; example does not match blog.example.com. Keep using link_type and domain_rating to narrow placements further.

Check the intended account before submitting indexing URLs. If a submission response is lost, check that same account’s URL list before retrying; indexing submissions do not support an idempotency key.

1. Call semalt_get_me for the token owner or semalt_list_accounts for account contexts available for selection, then explicitly pass the intended account_id to each account tool.
2. Use only account IDs returned by semalt_get_me or semalt_list_accounts when selecting an account. Treat linked_account_ids as relationship metadata, not as the account-selection list.
3. Call a semalt_list_*_sites tool in that account context to discover accessible site records.
4. Keep duplicate domains: they can represent distinct account or GSC records.
5. Use a site record’s id as site_id in site detail tools. Its owner_account.account_id identifies the owner; it does not automatically select that account. Use campaign_id from semalt_list_my_seo_campaigns for campaign tools.
6. Follow next_cursor while has_more is true.
7. For AI Analytics, use model=gpt-4.1-nano or model=gpt-5-nano.
8. Use site tags to organize and filter domains, and keyword groups to filter My SEO and Google SERP keyword data.
9. Ask for explicit confirmation before deleting a tag or keyword group, or removing tag/group members.

Call semalt_get_report_catalog(account_id) first. Each item contains a ready-to-fill definition_template and a scope.id_field that names the exact ID field. Copy the template into semalt_generate_report and replace its null scope ID with a value from the matching site or campaign tool.

For custom PDF branding, call semalt_list_report_white_labels(account_id), take the returned white_label_id, and add it inside the report definition. The white-label tool lists active labels with uploaded logos. Omit white_label_id to use Semalt branding.

semalt_list_report_white_labels({ "account_id": 20, "search": "Acme" })

{
  "data": [
    {
      "white_label_id": "42",
      "name": "Acme Reports",
      "company_name": "Acme Ltd"
    }
  ],
  "meta": { "limit": 50, "has_more": false }
}

semalt_get_report_catalog({ "account_id": 20 })

semalt_generate_report({
  "account_id": 20,
  "idempotency_key": "keywords-456-latest",
  "definition": {
    "kind": "table",
    "key": "my_seo.keywords",
"scope": { "campaign_id": 456 },
"period": { "type": "latest_snapshot" },
"filters": { "status": "approved" },
"white_label_id": "42"
},
"disposition": "attachment"
})

The template already contains kind, key, scope, period, and filters. Add only optional fields listed by that catalog item; white_label_id is the optional global field for custom PDF branding. For Search Console reports and supported tables, comparison: { type: "previous_period" } puts the preceding equal-length period into the same PDF.

semalt_generate_report({
  "account_id": 20,
  "idempotency_key": "gsc-123-2026-08-compare",
  "definition": {
    "kind": "report",
    "key": "search_console.site_overview",
    "scope": { "site_id": 123 },
    "period": { "type": "fixed", "date_from": "2026-08-01", "date_to": "2026-08-31" },
    "comparison": { "type": "previous_period" }
  }
})

Anyone holding a report link can open the PDF for up to 90 days, unless the links are revoked. Use inline to open it or attachment to download it. A report generation does not send email.

If a tool response is lost, reuse the same idempotency_key and definition. A processing result can be checked with semalt_get_report_run. A failed generation requires a new key for another attempt. Existing files and new links retain their original expiry.

The MCP server uses the API key from your Semalt account. Each account tool checks access to the selected account and then to the requested resource. A shared website alone does not grant access to its owner’s account context. Hidden and removed records are excluded.

A campaignid must belong to the selected accountid. Access to the selected account and requested resource is checked on every call; the selected account’s normal linked-group scope applies to site, tag and keyword-group operations. Product limits and campaign requirements continue to apply. Percentage allocation uses the same one-shot behavior as the dashboard: supplied approved-keyword percentages are fixed for that request, and omitted approved keywords share the remainder equally. It does not create a persistent fixed-percentage setting; call semalt_list_my_seo_keywords afterwards to inspect the resulting weights and shares.

Use the same data contracts without MCP through Public API v1.

View API documentation