SEODrafts MCP

The SEODrafts MCP server is the agent-facing control plane for project-scoped research, editorial review, post data, insights, audit, billing, and customer-owned publishing workflows. The API remains the tenant, authorization, concurrency, usage, and audit boundary. CMS credentials never enter MCP inputs or results.

Transports

• Hosted: stateless MCP Streamable HTTP at POST /mcp
• Local: stdio with --stdio (the default)

Both transports require a scoped, expiring sda_live_… agent API token. A dashboard session, internal key, publisher token, or CMS credential is not accepted.

Create a token

A workspace owner or admin creates the token in the dashboard or through the authenticated CLI. Grant only the required projects and scopes:

• read: projects:read, posts:read, opportunities:read, insights:read, integrations:read, billing:read, audit:read
• editorial writes: projects:write, posts:write, opportunities:write
• high-impact actions: posts:schedule, posts:approve, posts:generate

The raw secret is shown once, stored hash-only by the API, expires, can be revoked, and is audited per request.

Local stdio

Run the audited public package directly:

SEO_BLOG_ADMIN_AGENT_TOKEN='sda_live_…' \
npx --yes @wotaso/[email protected] --stdio

For development inside this monorepo:

npm --workspace apps/mcp run build
SEO_BLOG_ADMIN_AGENT_TOKEN='sda_live_…' \
node apps/mcp/dist/index.js --stdio

The stdio server can also read agentToken and apiUrl from the CLI config at ~/.config/seo-blog-admin/config.json. Environment variables take precedence.

Codex configuration:

[mcp_servers.seodrafts]
command = "npx"
args = ["--yes", "@wotaso/[email protected]", "--stdio"]
env_vars = ["SEO_BLOG_ADMIN_API_URL", "SEO_BLOG_ADMIN_AGENT_TOKEN"]
default_tools_approval_mode = "writes"

Hosted HTTP

MCP_HOST=127.0.0.1 \
MCP_PORT=3200 \
MCP_ALLOWED_HOSTS=localhost,127.0.0.1 \
SEODRAFTS_MCP_URL=http://127.0.0.1:3200 \
SEO_BLOG_ADMIN_API_URL=http://127.0.0.1:3100 \
npm --workspace apps/mcp run start

Clients send Authorization: Bearer <scoped-agent-token>. SEODRAFTS_MCP_URL is the exact public origin advertised by /server.json and /; set the environment-specific staging or production origin explicitly. Production requires TLS at the reverse proxy, and both the advertised MCP origin and upstream API origin must use HTTPS. HTTP is accepted only for loopback development.

[mcp_servers.seodrafts_hosted]
url = "https://mcp.seodrafts.com/mcp"
bearer_token_env_var = "SEO_BLOG_ADMIN_AGENT_TOKEN"
default_tools_approval_mode = "writes"

Agent surface

The server exposes:

• capability and project discovery, optimistic project-context updates, and a contrast-checked three-color hero palette
• cursor-paginated post and opportunity lists
• full post metadata with lossless, explicitly ranged Markdown chunks
• review-only post import and evidence-gated draft generation
• versioned post editing, separately scoped scheduling and approval, decline, restore, publish-health checks, and revision history
• bounded internal-link maintenance that stages same-ID/same-URL revisions for review and never publishes directly
• compact insights, integration health, billing state, and token-local audit events
• credential-free publisher integration recommendations and catalog data
• MCP resources for live capabilities and the integration catalog
• prompts for post review, opportunity planning, and publication-failure triage

Every mutation of an existing post and every publication-health check requires the exact latest expectedContentVersion and expectedStateVersion. Post creation and qualified generation create new review-only records, so they have no prior version. The Agent API requires bodyOffset (0–2,000,000) and bodyLimit (1,000–60,000) on every post read; MCP supplies defaults of 0 and 60,000 and always forwards both. Follow nextBodyOffset until it is null. Safe create/update inputs support the API's bounded 500,000-character Markdown limit.

Project-context replacement requires expectedContextVersion and the complete contextSourceUrls list (maximum four); preserve the current list unless deliberately changing provenance. Content edits clear stale approval, while schedules and publisher callbacks bind to a distinct approvalEpoch. Ordinary published-post mutations are immutable. stage_internal_link_refreshes is the narrow exception: it snapshots the current live body, inserts only exact natural anchors to verified live project URLs, and creates a normal review revision. Decline restores the snapshot; approval and scheduling remain separate.

Scheduling and approval are deliberately separate high-impact tools. approve_post does not accept scheduledAt; the caller must pass the live capability response's exact editorialResponsibilityVersion (currently 2026-07-23). Approval makes that exact version publish-eligible and clears any pre-existing automation schedule; call schedule_post afterward to set the approved delivery window. Approval remains annotated as a destructive/open-world write because a separately scheduled approved version can be delivered by the customer-owned publisher.

Security and observability contract

• Upstream calls are restricted to /api/v1/agent/v1; redirects and other API route families are rejected.
• Tokens are project- and scope-bounded, metered, rate-limited, expiring, revocable, and stored hash-only.
• Response bytes, body chunks, cursors, input fields, hosts, request rates, and concurrent requests are bounded. Hosted defaults allow at most 100 concurrent requests globally and four per token; agent generation is additionally bounded by the API.
• API 5xx details, exception text, authorization headers, bodies, cookies, and PII are not returned or sent to monitoring.
• API and MCP responses expose correlation-safe request IDs.
• A valid MCP_SENTRY_DSN (or SENTRY_DSN) is mandatory in production HTTP mode; startup and /health fail closed without deliverable error monitoring. Monitoring is privacy-minimised and tool tracing is deliberately disabled.
• Stateless HTTP prevents cross-tenant MCP session state.
• Direct publishing, arbitrary URLs, redirects, shell commands, SQL, credential access, token management, bulk publishing, and tenant pSEO factories are not exposed.