MCP CONNECTION GUIDE

Query and retrieve reports for the websites you want to understand.

Assess a backlink partner, a guest-post opportunity or a competitor directly in your AI client. Query Ahrefs DR, backlinks, search traffic and AI responses, then retrieve purchased reports to compare the evidence. You do not need to own the websites or have an Ahrefs account.

Start with the decision you need to make

Choose backlink partners

Compare DR, referring domains, Dofollow links and search traffic before contacting a website. Ask the AI to point out gaps rather than rely on a single score.

Assess guest-post opportunities

Review a publisher’s backlink profile, organic traffic countries and AI responses together to see whether it fits your intended audience.

Understand competitors

Compare reports for several websites and revisit purchased snapshots free. Have the AI identify the query and source-data dates before drawing conclusions.

Connect in three steps

  1. Create your connection

    Sign in with a verified account and open My account / Connect an AI client (MCP). For new website checks, enable “Allow lookups that use credits”, generate or replace your token, and update your client. Keep read-only access if you only want purchased history.

  2. Add the server to your AI client

    Choose a remote MCP server with Streamable HTTP. Enter the endpoint below, then set the Authorization header to Bearer followed by your token. If there is a separate Bearer Token field, paste only the token there.

  3. Read a saved report first

    Ask the AI to list your recent checks, then open a purchased result. These reads use no credits. Before a new check, confirm the domains, whether AI responses are included, and the credit cost.

Connection settings

Endpoint URL
https://ahrefsdr.com/mcp
Transport
Streamable HTTP
Authentication
Authorization: Bearer <token>

Use a client that supports remote Streamable HTTP and a custom Authorization header or Bearer Token. Clients that only support OAuth sign-in or local stdio need a compatible adapter. This is an Ahrefs DR Studio account token; no Ahrefs API key is needed.

How credits work

ActionCredits used
List history or open a purchased result0
New check: 1 website, base report1
New check: 1 website, base + AI responses2
New checks: 2 websites, base reports2
New checks: 2 websites, base + AI responses4
  • For N unique websites: base = N credits; base + AI = 2 × N. MCP checks one domain per tool call; ask the client to remove duplicates and confirm the total before multiple calls.
  • A failed base report returns its base credit. If only AI fails, its extra credit is returned and the base result remains. Pending requests can reserve credits until completion or recovery.
  • A new check or update uses credits. Reading your purchased report is free and preserves the report you acquired.
  • The daily MCP limit counts credits, not websites. It resets at 00:00 UTC, defaults to 20, and can be set from 1 to 2,000 when generating a token. It limits MCP lookups, does not add credits, and does not limit browser checks. Purchased credits remain valid for one year from each order.

Daily limits, account balance and free history

The daily limit counts credits, not tool calls

Set your daily MCP credit limit in My account when generating a token: 20 by default, from 1 to 2,000. With enough account balance, 20 credits allow up to 20 base checks or 10 checks with AI. History reads do not consume this allowance. The limit resets at 00:00 UTC and changing it requires a replacement token.

When the daily limit is reached

New checks are refused before they start. Wait for the UTC reset or adjust the limit and generate a replacement token. With 1 credit of allowance left, a base check can run but a 2-credit AI check cannot. Increasing the limit does not add account credits.

When your account credits run out

New paid checks cannot start, even if daily allowance remains. Add credits to continue. With a valid token, you can still list and read your purchased history for free, including after hitting the daily limit. An expired or revoked token must be replaced to read history too.

Reading history is different from a new check

History tools return your purchased report with its original query and data dates, without charging or updating it. Reading My Project and its purchased report is also free, even after the daily allowance is used up. A new check uses 1 credit, or 2 with AI. Ask the AI to say whether it is reading a saved report or starting a new paid check.

Example: Claude Code

In a private local MCP configuration, replace YOUR_MCP_TOKEN with the token generated in My account. Do not commit it or paste it into an AI conversation. This example is for Claude Code; other clients may use a different configuration format.

{
  "mcpServers": {
    "ahrefsdr": {
      "type": "http",
      "url": "https://ahrefsdr.com/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_MCP_TOKEN"
      }
    }
  }
}

After saving, reconnect and inspect the tools. Read-only tokens expose list_queries, get_query and get_my_project. Tokens allowing paid checks also expose check_domain.

Claude Code · MCP

What your AI can do

ToolPurpose
list_queriesList up to 50 recent account checks, including their IDs and query times. No credits.
get_queryRead one owned snapshot by query_id. No credits.
get_my_projectRead My Project and its purchased report as the default comparison baseline. No credits and no refresh. If no project is set, ask for a baseline URL.
check_domainRun one website check. Requires paid permission, sufficient balance and daily allowance, a UUID request_id, and confirm_credits = 1 (base) or 2 (with include_ai: true).

What to ask AI after connecting MCP

09

Start with one target website, or compare one or several targets with My Project to support a partnership, competition or promotion decision.

My Project is read automatically with get_my_project and used as the comparison baseline for free. You do not need to enter its URL again. If no project is pinned, the AI asks for your website URL; you can also choose a different baseline or assess a target without owning a site.

  1. For everyone

    Understand one website

    Assess [target domain] using DR, UR, backlinks, referring domains, organic search traffic and AI responses. Explain strengths, risks, potential reasons to investigate it further and evidence still missing.

  2. With a website

    Assess one backlink partner

    First call get_my_project and use its saved report as my baseline; ask for my website URL only if no project is available. Is [target domain] worth considering for a backlink partnership with my site? Confirm the partnership purpose. Review backlinks, Dofollow sources and traffic, with evidence-based pros and cons.

  3. For everyone

    Assess one affiliate candidate

    Evaluate [target domain] as an affiliate partner using organic traffic, TOP3 countries, backlinks and AI responses. Distinguish report evidence from audience fit, commissions and conversion data that require separate checks.

  4. For everyone

    Assess one guest-post opportunity

    I may contribute a guest post to [target domain] for [country or audience]. Evaluate backlink strength, organic traffic and countries; list strengths, risks and editorial or link-policy questions to confirm before contacting the publisher.

  5. With a website

    Compare My Project with one site

    First call get_my_project and use its saved report as my baseline; ask for my website URL only if no project is available. Compare it with [target domain] for [partnership or competitive purpose], noting strengths, gaps, complementarity and report dates.

  6. With a website

    Compare My Project with several sites

    First call get_my_project and use its saved report as my baseline; ask for my website URL only if no project is available. Rank them for [backlinks, affiliation, guest posts or competitor research]. Explain each site’s pros, cons and missing evidence beyond its score.

  7. For everyone

    Review competitor traffic and search ads

    Analyze [one or more competitor domains] using estimated organic traffic, keywords, TOP3 countries, paid keywords and estimated paid-search traffic and cost. Identify research questions without treating estimates as actual spending or profit.

  8. Exploring opportunities

    Explore an industry through a real site

    I do not own a site yet. Analyze [target domain or candidate list] in [industry] first, then discuss entry challenges, content and AI visibility opportunities, and questions to validate. Do not equate traffic with revenue.

  9. For everyone

    Revisit purchased reports for free

    List my recent checks and open a saved report I choose. State query and source-data dates, then summarize it. Only read purchased history; do not start new checks or spend credits.

For new website assessments, we recommend enabling “Allow lookups that use credits” in My account, generating or replacing your MCP token, and updating your client. Without it, you can only read this account’s purchased historical reports for free; you cannot start new website checks. New checks also need sufficient balance and daily MCP allowance.

Read purchased reports first. Before any new check, confirm the domains, whether AI responses are included, and the total credits with me. State query and data dates and missing fields; do not invent findings.

My account has three MCP AI modes: Off blocks new AI lookups; Auto lets the client choose and defaults off; Default on includes AI unless you explicitly request base only. include_ai: false selects base (1 credit), include_ai: true selects AI (2 credits) when permitted. Confirm the choice and total before querying. The web switch is separate; purchased project/history reads remain free and unchanged.

Historical data and new queries

The response identifies historical_read, new_query or existing_request in access.kind. queriedAt is the purchase/query time; dataAsOf gives the DR, base and AI source timestamps; retrievedAt is the read time. Times are ISO 8601 UTC. A missing historical timestamp stays unknown. Ask the AI to quote these times and access.billing debits, refunds and net credits.

Retries and token safety

Retry the same operation with the same request_id and identical inputs to avoid a second purchase. A new request_id represents a new check. Tokens are shown once and expire after 90 days. Generating a replacement invalidates the old token; revoke a token in My account when a client no longer needs access.

Connection troubleshooting

401 / cannot authenticate

Check that the token is valid, has not expired or been replaced, and is sent as Authorization: Bearer <token>.

Read-only or daily limit reached

Enable paid lookups and generate a replacement token, or adjust the daily limit and replace the token. Check your available account credits too.

Opening /mcp in a browser shows 405

The endpoint is for MCP POST requests, not a webpage. Use it in the client’s connection settings. Streamable HTTP is a transport label, not part of the URL.

403 / incompatible client

Some browser-based clients send a different Origin or cannot use custom headers. Use a compatible remote HTTP client. This service does not provide an OAuth sign-in flow.