MCP Setup

The SEO Ladders MCP server is a remote HTTP server hosted at https://www.seoladders.com/api/mcp. Your client connects directly over HTTPS — no local install, no background process, no npm package. Authentication uses an Authorization: Bearer header carrying your SEO Ladders API key.

One API key works across every site on your account. Each MCP connection targets a single site for its entire session, picked via the X-Site header on the connection. Add it inside your client config under headers alongside Authorization:

"headers": {
  "Authorization": "Bearer sk_live_••••••••••••••••",
  "X-Site": "acme.com"
}

Omit X-Site and the connection uses your active site — whichever one the dashboard sidebar switcher is currently pointing at. To switch which site Claude Code/Cursor/etc. operate on, either change the header in your config or open the dashboard and pick a different site there. Per-tool-call site overrides aren't supported yet — that's a planned follow-up if users ask for it.

• An SEO Ladders API key (see Authentication)
• An MCP-compatible client (Claude Code, Cursor, Windsurf, Codex, etc.)

Claude Code reads MCP servers from ~/.claude.json (user-scoped) or .mcp.json at the root of a project (project-scoped). Add SEO Ladders under the mcpServers key.

{
  "mcpServers": {
    "seoladders": {
      "type": "http",
      "url": "https://www.seoladders.com/api/mcp",
      "headers": {
        "Authorization": "Bearer sk_live_••••••••••••••••"
      }
    }
  }
}

Or add it via the CLI in one command — Claude Code writes the config for you:

claude mcp add --transport http seoladders https://www.seoladders.com/api/mcp \
  --header "Authorization: Bearer sk_live_••••••••••••••••"

Restart Claude Code (or run /mcp in-session). The SEO Ladders tools appear in the available-tools list — Claude can now research keywords, generate articles, and check refresh candidates without leaving the chat.

Cursor reads MCP configuration from ~/.cursor/mcp.json (or via the MCP settings panel in the UI).

{
  "mcpServers": {
    "seoladders": {
      "url": "https://www.seoladders.com/api/mcp",
      "headers": {
        "Authorization": "Bearer sk_live_••••••••••••••••"
      }
    }
  }
}

Restart Cursor. The tools become available to the agent and to inline AI completions.

Codex CLI reads MCP configuration from ~/.codex/config.toml. Same HTTP transport, same Bearer auth, different syntax.

[mcp_servers.seo-ladders]
url = "https://www.seoladders.com/api/mcp"

[mcp_servers.seo-ladders.headers]
Authorization = "Bearer sk_live_••••••••••••••••"

Restart Codex (or start a new session). The SEO Ladders tools register on connection and become callable from your CLI prompts.

Any MCP-compatible client follows the same pattern: register the server URL and pass your API key in an Authorization header (Bearer scheme). The exact config file location and syntax varies by client — check your client's MCP documentation. The endpoint and auth shape are always the same: https://www.seoladders.com/api/mcp with header Authorization: Bearer sk_live_....

The SEO Ladders MCP server exposes 5 tools — the research + writer loop. Each maps 1:1 to a REST API endpoint:

A typical workflow from your IDE — research, generate, publish — all via MCP tool calls:

// In Claude Code, Cursor, or any MCP client:
discover-keywords
// → Found rankable keywords for your site (no seed needed)

keyword-search "best crm for startups"
// → Up to 100 keywords with volume, KD, intent + DR recommendation

generate-article "monday alternatives"
// → articleId returned, generation runs in background (2-5 min)

get-article art_01HZ...
// → status: 'ready' with full article markdown

• “Authorization failed” / 401 — Check that the Authorization header value starts with Bearer (note the space) and your key starts with sk_live_. Generate or rotate the key from Developers → API Keys.
• “Tool not found” — Restart your MCP client after editing the config file. Tool registration happens on connection. In Claude Code you can also run /mcp to reconnect without restarting.
• “Connection refused” / network error — Verify the URL is https://www.seoladders.com/api/mcp (no trailing slash, https not http). Corporate firewalls and VPNs sometimes block streaming HTTP — try from a different network to isolate.
• “No site matching … found” — The hostname in your X-Site header doesn't match any site on your account. We normalize on lookup so https://www.acme.com/ and acme.com both work, but typos (e.g. acme.co) don't. Check the dashboard sidebar to see your exact site list.
• “Rate limited” — You've hit the per-month quota for that surface. Check the dashboard usage page or upgrade your plan.