---
title: "MCP server setup — seo-mcp"
description: "Connect the seo-mcp remote MCP server to Claude Code, Claude Desktop, Cursor or Codex."
url: "https://seo-mcp.io/docs/mcp"
---

# MCP server setup

One endpoint, 18 tools. The server profiles a project, returns the tips that
apply, orders them, and tracks what was applied. Deterministic: no AI runs inside the MCP.

Endpoint: https://seo-mcp.io/mcp (Streamable HTTP, Bearer key starting with `sk-`).

## Claude Code

```bash
claude mcp add --transport http seo-mcp https://seo-mcp.io/mcp --header "Authorization: Bearer sk-..."
```

## Claude Desktop

```json
{
  "mcpServers": {
    "seo-mcp": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://seo-mcp.io/mcp", "--header", "Authorization: Bearer sk-..."]
    }
  }
}
```

## Cursor

```json
{ "mcpServers": { "seo-mcp": { "url": "https://seo-mcp.io/mcp", "headers": { "Authorization": "Bearer sk-..." } } } }
```

## Codex

```toml
[mcp_servers.seo-mcp]
command = "npx"
args = ["-y", "mcp-remote", "https://seo-mcp.io/mcp", "--header", "Authorization: Bearer sk-..."]
```

## Tools

- `start_seo_session`: Entry point for every SEO request. Returns the workflow state for project_id: needs_profile (fresh project) or resumed (applied/verified counts).
- `profile_project`: Deterministically normalise repo signals (package.json, framework configs, homepage HTML, robots.txt, CMS markers) into a project profile with missing fields.
- `analyze_project`: Return published tips applicable to this project, ordered foundation → quick wins → growth. Safe tips only unless include_risky is true.
- `get_action_plan`: Ordered plan with why it applies, concrete steps, verification checks, prerequisites and risk warnings.
- `get_tip`: Fetch a tip by id or slug: brief, extended brief, prerequisites, how-to steps with verification, source, and the agent prompt.
- `get_tips_by_ids`: Batch fetch up to 20 tips by id or slug.
- `search_tips`: Full-text search (FTS5/BM25) over published tips with category/tag filters and a total count.
- `list_categories`: Category tree with published tip counts.
- `list_tags`: Tags with published tip counts, for filtering.
- `get_next_action`: Return the highest-priority unfinished tip for the project (foundation blockers first).
- `mark_applied`: Record progress for a project. Status: applied | skipped | not_applicable | in_progress.
- `verify_tip`: Record that the tip's verification check passed, with the observed evidence. Increments the anonymous verification success rate.
- `get_progress`: List recorded tips for a project with status, verification and evidence.
- `report`: Deterministic session report for a project: profile summary, applied and verified tips, open next actions. Use it to close a session.
- `reset_progress`: Delete all recorded progress for a project. Destructive; confirm with the user first.
- `whats_new`: Tips published or updated since a timestamp (default: last 30 days).
- `audit_html`: Run deterministic SEO checks against supplied HTML, files from the repo, or a public URL (SSRF-guarded fetch). Returns findings with evidence and the tip ids that fix them. No AI.
- `submit_feedback`: Report a tip as outdated, wrong, or that it worked. The message reaches the editors.

## Sample session

```text
→ call start_seo_session { "project_id": "riverstone-web" }
← { "state": "needs_profile", "next_step": "Inspect package.json and the routes, then call profile_project." }

→ call profile_project { "project_id": "riverstone-web", "site_type": "saas", "stack": ["nextjs"] }
← { "profile_id": "…", "next_step": "Call get_next_action." }
```

`project_id` is the repository name, so the plan resumes across chats. State-changing calls return
`next_step`; follow it instead of guessing.

## OAuth and redirects

claude.ai and Claude Desktop discover the authorization server from
`/.well-known/oauth-protected-resource`, register a public client and use PKCE. Approval issues a
normal revocable key. Revocation: https://seo-mcp.io/dashboard.