Ahrefs MCP Server: Setup for Claude, Codex and the Rest
The first thing that will happen when you connect Ahrefs to an AI client is that nothing happens. No error, no tools, just a server that sits there looking connected. In my case the cause was mundane: Ahrefs ships two different MCP servers and two different kinds of API key, and only one of the four possible pairings is the one you want today. Nobody tells you which one you picked. That is the…
When connecting Ahrefs to an AI client like Claude or Codex, it is crucial to understand the setup process. First, note that Ahrefs ships two distinct MCP servers and two kinds of API keys, but only one pairing is suitable for use. This guide outlines the correct setup based on my experience.
Upon connecting Ahrefs to an AI client, no immediate error or indication appears. Instead, a server remains idle, seemingly connected. My issue stemmed from using an incorrect pairing of the two possible options. This guide aims to clarify the process and prevent similar confusion.
The primary server Ahrefs utilizes is located at https://api.ahrefs.com/mcp/mcp, adhering to the Streamable HTTP protocol. Older local servers, published on npm as @ahrefs/mcp, are now archived and no longer functional. The current remote server requires an MCP-scoped key, which must be generated separately in your Ahrefs account.
The API key and MCP key are not interchangeable, as stated explicitly by Ahrefs. There are four pairing combinations, but only one is sensible today: using an API v3 key with an MCP-scoped key. Connecting to the wrong server will result in an unauthorized error or a server with no tools, leading to confusion and wasted time.
Authentication can be achieved through OAuth or a bearer token. OAuth is suitable for interactive work, but for headless operations, a bearer token is more practical. The bearer token allows for immediate authentication without the need for a browser or token refresh.
Claude Code and Codex both support connecting to the Ahrefs MCP server. Claude Code utilizes a project scope for key storage, while Codex relies on a globally accessible configuration file. Both services have unique nuances that may cause confusion during setup.
In summary, connecting Ahrefs to an AI client requires careful server selection, authentication method choice, and understanding the tools and endpoints available. By following this guide, users can avoid the common pitfalls and setup process that led to wasted time and frustration.
Written by urgent.news from Dev.to's reporting — not their text. Machine-written — may contain errors; check the original before relying on it.
