OpenSEO — Measured SEO Data Plane

OpenSEO supplies evidence; mktg skills supply methodology. Communicate only through OpenSEO's MCP-over-HTTP endpoint. There is no general OpenSEO REST research API, and mktg never calls DataForSEO directly.

On Activation

1. Run mktg seo status --json --fields readiness,catalog,project,bindingCorrupt,state.
2. Interpret readiness:
   • hosted_oauth_ready: agent MCP client is authenticated interactively.
   • hosted_api_key_ready: headless hosted MCP can use OPENSEO_API_KEY.
   • selfhost_ready: bound/connected non-hosted MCP endpoint; local Docker HTTP is allowed only on loopback.
   • not_configured: continue through Exa/crawl/manual evidence and label KD, volume, CPC, authority, and rank unknown.
3. Read .seo/openseo.json. If absent and project-scoped tools are needed, use openseo-project-setup.
4. Read get_project_context before rebuying research. Use its research log to identify still-fresh evidence.
5. Select only the tools needed from the v0.1.6 tool map.

Authentication

• Root .mcp.json intentionally declares the hosted URL without a bearer header so MCP clients can perform OpenSEO OAuth.
• Headless clients may add Authorization: Bearer ${OPENSEO_API_KEY} or x-api-key: ${OPENSEO_API_KEY} in their private client config. Never write a key value into the repository.
• OPENSEO_MCP_URL overrides the endpoint for self-hosting. Hosted default is https://app.openseo.so/mcp.
• mktg catalog info openseo reports headless API-key readiness; mktg seo status distinguishes OAuth, API key, and self-host modes.

Route Evidence, Do Not Duplicate Playbooks

Need	OpenSEO evidence	mktg owner
Keyword demand/opportunity	keyword research, metrics, ranked terms, GSC	openseo-keyword-research
Page mapping/cannibalization	query+page GSC, SERPs, ranked URLs	openseo-keyword-clustering
Market/competitor	SERP competitors, domain/ranked terms, backlink profiles	competitive OpenSEO skills
Technical/indexing	site audit, URL inspection, GSC	seo-audit
Local visibility	business, local SERP, reviews, categories, rank grid	seo-audit with local mode/brief
Organic outcomes	GA4 landing/page/event/acquisition/opportunity tools	seo-audit, seo-content, seo-machine
AEO hypotheses	SERP, index, audit, backlink, GSC, GA4 evidence only	ai-seo owns direct answer-engine observations

Cost and Mutation Policy

Before a paid batch, state the exact tool(s), item counts, requested limits, and cost shape. OpenSEO's server requests confirmation above its large-credit threshold, but mktg still asks whenever the planned spend is material or recurring.

Separate spend from mutation:

• whoami, project/context reads, saved-keyword reads, GSC, and GA4 are free reads.
• save_keywords, create_project, tags, and update_project_context mutate shared account state but do not themselves consume DataForSEO credits; confirm broad/destructive changes.
• research, SERP, backlinks, local SEO, site audit, and rank runs may consume credits.
• scheduled rank tracking requires estimate_rank_tracker_cost, explicit approval, and the approved credit ceiling passed to the write/run call.

State Contract

Evidence	Local contract
project/domain/MCP URL	.seo/openseo.json
keyword transfer	.seo/keywords-sync.json → mktg seo sync-keywords --confirm
rank observations	.seo/rank-snapshots/<date>.json
backlinks	.seo/backlinks/<date>.json with target scope, pagination, and provider limits
GSC / GA4 exports	.seo/gsc/, .seo/ga4/ when a file snapshot is needed
site audits	.seo/audits/<audit-id>.json plus summary

OpenSEO remains the measurement backend; brand/ and the active playbook tracker remain mktg's decision memory.

Anti-Patterns

• Inventing REST endpoints — upstream automation is MCP-over-HTTP; guessed REST paths fail and misstate the security boundary.
• Treating configured: false as proof OAuth is disconnected — catalog readiness is headless env readiness; mktg seo status owns the richer truth.
• Calling DataForSEO directly — this bypasses OpenSEO's project, usage, and cost controls.
• Calling free account mutations “paid research” — spend and shared-state risk need different approvals.
• Saving only backlink totals — scope (exact, subfolder, domain, subdomains), pagination, and provider limitations determine what totals mean.
• Claiming OpenSEO MCP measures AI answers — v0.1.6 has no AI Visibility MCP tools. Use ai-seo direct observations and OpenSEO supporting evidence.

Progressive Enhancement

Level	Behavior
L0	Qualitative web/manual evidence; metrics unknown.
L1	Hosted OAuth or API key exposes measured MCP tools.
L2	Bound project/context avoids duplicate spend and enables GSC/GA4.
L3	Synced snapshots feed mktg playbooks and long-arc trackers.

After writing artifacts, log completion with mktg run openseo --complete --writes <paths> --result success --json.

---

OpenSEO integration targets every-app/open-seo v0.1.6 over an MIT-safe HTTP/MCP boundary.