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

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

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

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.