Overview
dx-seo exposes a self-hosted MCP server at POST /mcp. Once a Claude Code session can reach it, the /seo-* commands push their results to your dashboard automatically. Every push is authenticated with an API key you mint in Settings.
Sync is best-effort. If the dashboard MCP isn't connected, the commands still run exactly as they would standalone — they just skip the push step.
Steps
Mint an API key
In the dashboard, go to Settings → API keys and create a key. It is an opaque oat_… token shown once — copy it now.
Register the MCP server
Add dx-seo as a user-scoped MCP server so every project can push to it:
claude mcp add --scope user --transport http seo https://<your-dx-seo-host>/mcp \
--header "Authorization: Bearer oat_…"The server name is free (the commands use tool names, not the server name); seo keeps it short. For local development the endpoint is http://localhost:8080/mcp — register that one project-scoped under a different name so it does not shadow the user-scoped entry.
Backfill your history (one time)
Existing projects have config and ledger history from before the dashboard. Sync it all once:
It's idempotent — safe to re-run.
What /seo-migrate backfills
/seo-migrate walks every registered project and pushes its seo/config.json (via seo_upsert_site) and every seo/actions.jsonl entry (via seo_sync_actions), then reads back per-site totals with seo_overview.
Keyword tables and content briefs from past runs were never persisted to disk, so they can't be backfilled. They accrue on the dashboard from the next command run onward.
Verify the connection
Ask the connected session to call seo_overview, or run any command that pushes — for example /seo-quick-wins — and watch a site appear on the dashboard.
The MCP tools
seo_upsert_site— register or update a tracked site fromseo/config.json. Call this first.seo_sync_actions— upsertseo/actions.jsonlledger entries, verbatim. Push the whole file; it's idempotent.seo_push_keywords— keyword metric snapshots. Append-only; the dashboard keeps history.seo_push_recommendations— next-content briefs. Upserted by slug.seo_push_authority— the proven-KD-ceiling snapshot from/seo-analyze. Overwrites the previous one.seo_overview— read back per-site totals, verify-due counts, and win rates.whoami/echo— connectivity checks.
Authentication
Send the key as either Authorization: Bearer oat_… or X-API-Key: oat_…. The /mcp endpoint returns 401 with a WWW-Authenticate header when no credential is present, which is what triggers an MCP client's OAuth discovery flow.