Semrush hosts an official MCP server that reaches every SEO report through a discover, describe and execute pattern, and keeps the API agencies have built reporting on for years. Both read the same data and spend the same API units. They diverge on writes, on Local SEO, on which plan unlocks them and on whose key every request runs under. This guide compares both for an SEO agent, shows why units make spend a production risk, and how to run a key per client.
Your agent does SEO work for your customers. It needs to explain why a client's organic traffic dropped after a core update, find the referring domains that link to three competitors but not to the client, pull search volume for a list of keywords before a content brief goes out, or check how a dentist's practice ranks on Google Maps across a five-mile grid. Semrush now hosts an official Model Context Protocol (MCP) server and ships connectors for Claude, ChatGPT, Perplexity, Copilot, and Notion on top of it. It also has the API that agencies have built reporting on for years. They read the same data and bill the same API units. They diverge on writes, on Local SEO, on which plan unlocks them, and on whose key every request runs under. Here's how to pick.
The Semrush MCP server is hosted by Semrush at https://mcp.semrush.com/v2/mcp and supports Streamable HTTP only. Nothing runs locally. Earlier third-party setup guides point at /v1/mcp; Semrush's current docs list only /v2/mcp. Connecting Claude Code is one line: claude mcp add semrush https://mcp.semrush.com/v2/mcp -t http, then /mcp to sign in. Semrush also lists official apps or connectors for Claude, ChatGPT, Microsoft Copilot, Perplexity, Lovable, and Notion, and config snippets for Cursor, VS Code, and Antigravity. Semrush announced the Perplexity connector on June 3, 2026, and PPC Land reported the Claude connector on August 26, 2026.
The server's 14 tools follow a discover, describe, execute pattern. Twelve discovery tools map to Semrush report families: domain_overview, organic_research, keyword_research, competitors_research, backlinks_research, audience_research, traffic_overview, paid_search_research, shopping_research, position_tracking, site_audit, and projects. The model picks a report, calls get_report_schema for its parameters, and runs it with execute_report. Semrush describes the data scope as all SEO API endpoints, all Trends API endpoints subject to your subscription, and read-only Projects API (v3) methods: "users can read project data but cannot create projects, change settings, or take other actions."
Access needs an eligible plan. The SEO data comes with Semrush One Starter, Semrush One Pro+, SEO Classic Pro, or SEO Classic Guru, which include 50,000 API units refreshed on renewal; SEO Classic Business and Semrush One Advanced get MCP with a units package of 2M, 5M, 10M, or 20M. Traffic and market data needs a Trends API Basic or Premium plan. Semrush says there are no MCP usage fees beyond units.
The Semrush API is several APIs under one key system (API overview):
Auth is an API key. The v3 key goes in the key query parameter, there is "only one v3 key in your account that's generated automatically," and it "can't be revoked or deleted." v4 keys go in Authorization: Apikey <YOUR_API_KEY>; you can create up to 100, each "Read-only" (GET only) or "Read and write", each with its own TTL. OAuth 2.0 survives only for the deprecated Projects and Listing Management APIs, through a Device Authorization Grant (RFC 8628) or a Support-issued client, with 7-day access tokens.
Standard API access is gated harder than MCP. Semrush's how to get the API page says to "Upgrade to the Business subscription to buy API units and generate an API key," and after upgrading, "the number of units will still be zero."
The read side is close to parity. Because execute_report can run any SEO API report, the MCP server reaches the same domain, keyword, and backlink data the Standard API does, and on Pro and Guru plans it reaches it without a Business upgrade. Everything else splits cleanly. The MCP server cannot change anything in Semrush, and it doesn't touch the Local API at all. An agent that manages Position Tracking campaigns, runs Map Rank Tracker scans for multi-location clients, or replies to Google reviews is an API agent.
Semrush's API is wide and terse. "Which keywords does competitor.com rank for in the top 10 that we don't" on the raw API means knowing the report is domain_organic (or domain_organic_organic for the comparison), knowing the database code, building export_columns=Ph,Po,Nq,Cp,Ur,Tr from two-letter column codes, encoding a display_filter, and parsing semicolon-separated CSV. The v4 backlink resources are JSON, but scope must be one of ROOT_DOMAIN, SUBDOMAIN, SUBFOLDER, or PAGE, and not every method accepts every value.
On MCP, the model calls organic_research to find the right report, get_report_schema to learn its parameters, and execute_report to run it. Semrush owns the mapping from intent to report to parameters, across v3 and v4. Writing the schema is the hard part. Not the API call.
The tradeoff is that Semrush owns the surface, and the surface is a meta-tool. Two tools decide everything the model does, so tool selection tells you little about cost or scope until the execute_report arguments land. The endpoint path has already moved from /v1/mcp to /v2/mcp. An agent tuned against today's report schemas can change behavior without a release on your side.
On the MCP path, OAuth 2.1 is the default: the client redirects the user to Semrush's login page and the grant carries that user's Semrush account and plan. Semrush's troubleshooting note says a "redirect URI ... is not allowed" or 400 error during OAuth means contacting Semrush Support, so a custom MCP client in your own product should expect a redirect allowlisting step, not self-service registration. Clients that can't do OAuth send Authorization: Apikey YOUR_API_KEY. For Claude Team and Enterprise, Semrush also supports enterprise-managed authorization, where a corporate account owner trusts exactly one issuer, either Claude or Okta, and members sign in through it.
On the direct API path, every credential is an account key. The v3 key is the sharp edge for agents: one per account, generated automatically, never revocable. A leaked v3 key is a permanent liability until Semrush Support intervenes. v4 keys fix most of that. You can mint a key per integration, mark it "Read-only" so POST, PUT, PATCH, and DELETE fail, and give it a TTL so it expires on its own. Map Rank Tracker "requires a Version 4 API key," and Scalekit's own quickstart for the semrush connector calls semrush_get_map_rank_limits, so a v4 key is the one to hand the connector.
Semrush adds a twist that matters for agents: every key is an account, and units are an account balance. There is no per-user scope inside a Semrush account. Two people at the same agency sharing a Semrush login share one key's reach, one 10-requests-per-second limit, and one unit balance. What the user can't do, the agent can't do, but in Semrush "the user" is the account.
In a multi-tenant B2B agent, MCP's OAuth flow gives you a token per user and the direct API gives you a key per user or per customer account. In neither case does the path itself solve storage, rotation, or revocation; those are infrastructure problems regardless of which path you choose.
Semrush makes the boundary financial as well as about access. If your agent runs every customer's queries through one Semrush key, every customer's backlink audit spends your units, every customer's loop counts against your 10 simultaneous requests, and every customer can see whatever your projects contain if the prompt lets a project_id through. With a key per customer, each customer's agent spends that customer's units and sees that customer's projects. That multiplies the keys you hold.
Recommended reading: OAuth vs API keys for AI agents
On the MCP path, Semrush hosts the server, owns the report schemas, and enforces the account's plan. You own each user's OAuth session if your product is the MCP client, or a key per account if it runs headless. You also own the unit budget, which is the real production risk. A model that runs execute_report on domain_organic without a display_limit can return thousands of lines at 10 units each, or 50 each for historical data. A 100-row backlink gap at 40 units per row is 4,000 units. On a 50,000-unit Pro allowance, a few curious conversations exhaust the month, and Semrush's own guidance is to specify result counts, databases, and filters in the prompt.
On the API path, you own report selection, CSV and JSON parsing, pagination, retries, and the key lifecycle. Semrush's usage restrictions cap every account at 10 requests per second and 10 simultaneous requests, and forbid caching data for more than a month without written consent. When units run out, per-line SEO and Trends reports return only the lines your balance covers, then ERROR 132; Projects and Local APIs return 403 (API unit balance). A partial result that looks complete is the failure mode to guard against. GET https://www.semrush.com/users/countapiunits.html?key=YOUR_API_KEY returns the remaining balance, so a pipeline can check before it spends. Requests that return no data cost nothing.
There are no webhooks to react to. On both paths, a rank drop or a new toxic backlink is something your agent discovers on a schedule.
Use Semrush MCP when:
Use the Semrush API when:
Both paths hand you a Semrush credential. Neither hands you a vault. An agency platform serving 120 client businesses, each with its own Semrush account, holds 120 keys on the API path, or 120 OAuth grants on the MCP path if your product is the client. On the API path, each key is a unit balance and a 10-requests-per-second budget, not just a secret. If a customer gives you their v3 key, it can never be revoked; if they give you a v4 key, it may expire on a TTL you didn't set, and your agent finds out when a scheduled report returns 403. Each must be stored encrypted, kept out of logs and LLM context, mapped to exactly one customer, and deleted when that customer churns.
The tempting shortcut is your own Business account and one key for everyone. Fewer secrets, larger blast radius per secret: one leaked key spends your whole unit balance, one runaway loop throttles every customer at once, and every customer's agent can read every project in your account.
Scalekit's semrush connector stores each user's Semrush API key encrypted in the token vault and injects it into every call, so the MCP vs API decision doesn't change your auth infrastructure. Your agent passes an identifier; credentials never touch the agent runtime or the LLM context.
Recommended reading: why a token vault matters for AI agent workflows
Scalekit's semrush connector is an API-path connector built by Scalekit with 54 tools: 35 read-only, 14 write, and 5 destructive. It covers v4 backlink analytics, keyword metrics, projects, Map Rank Tracker, Listing Management, the Google Business Profile tool, and Review Management. It authenticates with API keys: each user connects their own Semrush API key once, and Scalekit sends it with every call. The core set for SEO analysis:
In the Scalekit dashboard, go to AgentKit > Connections and create a Semrush connection. The name you give it is the connection_name your code passes, and the string must match the dashboard exactly. This is the most common integration error.
Ask each customer for a v4 key generated for your integration, not their account's v3 key. A v4 key can be deleted when they leave, given a TTL, and marked "Read-only" if your agent only reports. Copy SCALEKIT_ENVIRONMENT_URL, SCALEKIT_CLIENT_ID, and SCALEKIT_CLIENT_SECRET from Developers > API Credentials into .env.
get_or_create_connected_account returns the connected account for an identifier. If it is not ACTIVE, get_authorization_link returns a link to Scalekit's Hosted Connect Widget. For an API-key connection like Semrush, the widget shows a form where the user enters their key instead of an OAuth consent screen. Scalekit encrypts and stores it; your code never receives it. The identifier should map to one Semrush account, because a key acts as exactly one account and spends exactly one unit balance. semrush_get_map_rank_limits then confirms the key works and is a v4 key.
This is not a catalog load. The agent asks for the tools this connected account is authorized to call, then narrows them to the seven a backlink analyst needs. Loading all 54 Semrush tools would put semrush_delete_project, semrush_delete_location, and semrush_add_review_comment in front of a model whose job is to compare link profiles. None of the seven below changes anything in Semrush.
The loop runs until the model stops requesting tools. Every call spends this customer's API units, so the system prompt sets row limits the way Semrush recommends, and the loop stops the model after a fixed number of tool calls.
For pipelines, skip the model. execute_tool runs one tool with a fixed input and returns data plus an execution_id you can log. This monthly job runs per client: it reads the backlink overview at 45 units, the last six months of history at 40 units per row, and the keyword metrics for the client's tracked head terms at 20 units each. The unit cost is fixed before it runs, which is the property an agency billing model needs and an open-ended MCP conversation can't give you.
The writes are where the API path earns its place. semrush_create_map_rank_campaign and semrush_collect_map_rank_campaign set up and run a Google Maps grid scan, and collection spends Map Rank Tracker credits equal to grid points times keywords, which semrush_get_map_rank_limits reports before you start. semrush_add_review_comment posts a reply to a Google review. Neither belongs in a model's default tool set; both fit a pipeline with a human approval step in front of them, and neither exists on the Semrush MCP server.
The tools we could verify in Scalekit's semrush connector cover v4 resources. For a v4 endpoint the connector doesn't wrap, Scalekit's proxied API calls keep the customer's key in the vault. v3 analytics reports such as domain_organic are different: the v3 key travels in the key query parameter, so that call and that key stay in your code. The raw shape, including the two failure modes that matter, looks like this:
The v3 key in that key parameter ends up in request URLs, which is where proxies and access logs keep it. That's one more reason to prefer v4 keys in the Authorization: Apikey header for anything new.
The semrush connector has 54 tools. At roughly 200 tokens each, that is about 10,800 tokens of tool definitions before the agent does any work. A model choosing among semrush_get_backlinks_overview, semrush_compare_backlink_profiles, semrush_get_backlinks_history, and semrush_get_authority_score_distribution picks the wrong report more often than a model holding only the one it needs, and in Semrush the wrong report costs units. Overreach is the bigger risk: a reporting assistant that also holds semrush_delete_project and semrush_update_location can remove a client's tracking history or change a business's hours on a bad inference. The fix is not better prompting. It is surface reduction. A Scalekit virtual MCP server declares exactly which tools an agent role can see, and session tokens keep each run bound to one user's connected accounts. Docs: set up a virtual MCP server.
One server definition serves every customer. Before each run, check that the customer's accounts are active and mint a short-lived session token scoped to them. Any MCP client that speaks Streamable HTTP can connect; this example uses langchain-mcp-adapters (pip install langchain-mcp-adapters) and passes the token as a Bearer header.
The agent sees six tools instead of 54 plus everything Slack exposes. The endpoint is static; the identity is per user. Semrush's MCP docs describe no way to narrow its server like this: every client gets the same 14 tools, and execute_report can run any report the account's plan allows.
Every execute_tool call returns an execution_id, and every execution is attributed to a connected account, which maps to one customer and one Semrush account. When a client asks why their API units ran out on the 9th, or who deleted a Position Tracking project, the answer is a lookup, not an investigation. Because each tool's unit cost is published per request or per row, your execution log is also a spend log you can reconcile against the balance from countapiunits.html.
Attribution is where the paths differ. Semrush records usage against the account behind the key. If one key serves every user of your product, Semrush sees one account doing everything, and your execution log is the only place that records which user and which prompt spent the units. Shared credentials work for a single user. They do not survive a second user.
Recommended reading: audit trails for agent auth
If your agent is an SEO lead's or content strategist's assistant in Claude, ChatGPT, or Perplexity, answering questions about keywords, competitors, and backlinks with a person deciding what's worth the units, Semrush's hosted MCP server is a good fit, and on Pro or Guru plans it's the only way to reach Standard API data without a Business upgrade. If your agent runs on a schedule for many clients, needs a fixed unit cost per run, writes projects or Map Rank Tracker campaigns, or manages listings and reviews, build against the Semrush API, where you choose the report, the row limit, and a v4 key you can scope and expire. Either way, you hold a Semrush key per customer that is also that customer's unit balance, and that's what needs production-grade infrastructure.
Yes. Semrush hosts a remote MCP server over Streamable HTTP with 14 tools: 12 discovery tools for report families plus a schema tool and an execute tool that together reach every SEO API report, the Trends reports your plan includes and read-only project data. Semrush also ships connectors for Claude, ChatGPT, Perplexity, Copilot and Notion.
No. Semrush says users can read project data but cannot create projects, change settings or take other actions, and the server has no Local API coverage. Creating Position Tracking projects, running Map Rank Tracker scans, updating listings and replying to reviews all require the API.
Both paths spend the same units, often per returned line. A loose report request without a row limit can return thousands of lines at 10 or more units each, so a few curious conversations can exhaust a 50,000-unit monthly allowance. Set row limits, cap tool calls per run and check the balance before scheduled jobs.
The v3 key is one per account, generated automatically, passed as a query parameter and cannot be revoked or deleted. Version 4 keys go in a request header, up to 100 per account, each read-only or read and write with its own expiration. Prefer v4 keys for any agent integration.
MCP access comes with Semrush One Starter and Pro+ and SEO Classic Pro and Guru, with 50,000 units refreshed on renewal, while higher plans buy larger unit packages. Standard API keys require the Business subscription, which starts with zero units until you buy a package. Traffic data needs a Trends API plan.
Each customer enters a Semrush API key once on a hosted page, and Scalekit stores it encrypted in a vault and sends it with every call. The connector exposes 54 tools, 35 read, 14 write and 5 destructive, covering backlinks, keyword metrics, projects, Map Rank Tracker, listings, Business Profile and reviews.
Browse the Scalekit Semrush connector and the Semrush connector docs with the full tool list. See Scalekit pricing, or talk to us.
