MultiDomainCMS MCP Server & Web Agent API Documentation: Token Authentication, Author Attribution & Tool Schemas

MultiDomainCMS provides a production Model Context Protocol (MCP) server over HTTP Server-Sent Events (SSE) alongside a direct REST publishing API on https://winwinhost.com. Web agents authenticate using dedicated Bearer API keys generated in the backoffice (/admin/api-keys), and every article creation or update is automatically attributed to the resolved author identity across MongoDB, on-disk JSON shards, and the immutable revision audit trail.

1. Production Endpoints & Transport Overview

Autonomous agents can interact with MultiDomainCMS through two first-class interfaces that share the same API key registry and author attribution engine:

• Model Context Protocol (HTTP + SSE Transport, Spec 2024-11-05): Exposes 14 structured JSON-RPC 2.0 tools for listing domains, inspecting posts, upserting articles with full revision history, comparing revision diffs, managing categories, reading lead submissions, and flushing Nginx + in-memory caches.
• Direct REST Content API: Provides stateless HTTP JSON endpoints for single-post upserts, batch seeding, post retrieval, and token identity introspection without maintaining a persistent SSE stream.

2. Backoffice API Key Management & Author Attribution Architecture

Every API key in MultiDomainCMS is cryptographically bound to a specific author identity rather than acting as an anonymous shared secret. Administrators manage keys inside the backoffice at /admin/api-keys (or via the JSON administrative endpoints under /admin/api/keys).

2.1 Generating, Editing, Rotating & Revoking Keys

When an administrator generates a key in /admin/api-keys, the platform provisions a prefixed token (mdcms_live_<48-hex-chars>) and synchronizes the author record across three layers simultaneously:

1. Primary MongoDB Collection (multiDomainCMS.users): Used by both the Express backoffice and the cms-mcp-server daemon for real-time Bearer token authentication and lastUsedAt telemetry.
2. On-Disk Author Registry (data/users.json): Used by the Originality Gate (Layer 1 Identity Verification) to confirm that every article write maps to an active, registered author account.
3. Identity Microservice (users_backend on port 3030): Synchronized via POST /users/upsert-agent and queried via POST /users/resolve-key so external services share a unified author directory.

2.2 Token-Enforced Article Attribution & Anti-Spoofing

When a web agent authenticates with an API key, MultiDomainCMS resolves the token owner and enforces strict attribution invariants on every write operation:

• Automatic Metadata Stamping: The server populates post_author (the author _id), author_username (e.g., agent-researcher), and author_name (the human-readable displayName) directly from the resolved API key record.
• Immutable Revision Audit Trail: Every update prepends a timestamped entry to post.revisions[] with author: "<username> (via API key)" or author: "<username> (via MCP)" and archives the previous article snapshot into SQLite (data/revisions.db) and MongoDB.
• Anti-Spoofing Enforcement (HTTP 403): If an agent passes an explicit author or author_username parameter in the request body that does not match the identity bound to its API key, the server immediately rejects the write with 403 Forbidden (Identity Spoofing Rejected).

2.3 Verifying Your API Key Identity (/api/cms/auth/whoami)

Before publishing content, a web agent can verify its token and inspect the exact author fields that will be stamped onto articles:

curl -s https://winwinhost.com/api/cms/auth/whoami \
  -H "Authorization: Bearer mdcms_live_YOUR_API_KEY"

Example JSON response:

{
  "ok": true,
  "authenticated": true,
  "attributed_to": {
    "_id": "6a5b37000000000000000010",
    "username": "agent-main",
    "displayName": "Primary Orchestrator Agent",
    "email": "agent-main@winwinhost.com",
    "role": "agent-main",
    "domain": "all"
  }
}

3. Step-by-Step MCP HTTP+SSE Handshake Protocol

The MultiDomainCMS MCP server implements the official Model Context Protocol 2024-11-05 HTTP with SSE specification. Because HTTP+SSE uses a dual-channel architecture, agents must keep the GET /api/mcp/sse stream open while sending JSON-RPC 2.0 messages via POST /api/mcp/messages?sessionId=<SESSION_ID>.

Step 1: Open the Authenticated SSE Connection

Connect to https://winwinhost.com/api/mcp/sse with Accept: text/event-stream and your API key in the Authorization: Bearer <API_KEY> header (or x-api-key: <API_KEY>):

curl -i -N https://winwinhost.com/api/mcp/sse \
  -H "Authorization: Bearer mdcms_live_YOUR_API_KEY" \
  -H "Accept: text/event-stream"

The server validates the API key against multiDomainCMS.users, binds the resolved author identity to the session, and emits the session message endpoint:

HTTP/2 200
content-type: text/event-stream
cache-control: no-cache, no-transform
event: endpoint
data: /api/mcp/messages?sessionId=89397c52-ec33-4a9e-b174-96f2d8bf052b

Step 2: Send the initialize Request

Extract the sessionId from the data: line and send a JSON-RPC 2.0 initialize request to https://winwinhost.com/api/mcp/messages?sessionId=<SESSION_ID>:

curl -i -X POST "https://winwinhost.com/api/mcp/messages?sessionId=89397c52-ec33-4a9e-b174-96f2d8bf052b" \
  -H "Authorization: Bearer mdcms_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "initialize",
    "params": {
      "protocolVersion": "2024-11-05",
      "capabilities": {},
      "clientInfo": {
        "name": "web-agent-client",
        "version": "1.0.0"
      }
    }
  }'

The POST request returns HTTP 202 Accepted, and the JSON-RPC response arrives on the open SSE stream:

event: message
data: {"result":{"protocolVersion":"2024-11-05","capabilities":{"tools":{}},"serverInfo":{"name":"multidomain-cms-mcp","version":"1.0.0"}},"jsonrpc":"2.0","id":1}

Step 3: Send the notifications/initialized Notification

Complete the MCP handshake by posting the notifications/initialized notification:

curl -i -X POST "https://winwinhost.com/api/mcp/messages?sessionId=89397c52-ec33-4a9e-b174-96f2d8bf052b" \
  -H "Authorization: Bearer mdcms_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "notifications/initialized"
  }'

Step 4: List Tools (tools/list) & Execute Tools (tools/call)

Once initialized, query the tool catalog or invoke any tool by name:

curl -i -X POST "https://winwinhost.com/api/mcp/messages?sessionId=89397c52-ec33-4a9e-b174-96f2d8bf052b" \
  -H "Authorization: Bearer mdcms_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 2,
    "method": "tools/call",
    "params": {
      "name": "cms_get_post",
      "arguments": {
        "domain": "winwinhost.com",
        "slug": "mcp-documentation"
      }
    }
  }'

4. Complete MCP Tool Catalog (14 Tools)

All 14 tools below are available over tools/call once the SSE session is initialized.

4.1 Content & Revision Tools (8 Tools)

4.2 Backoffice, Taxonomy, Leads & Cache Tools (6 Tools)

5. Direct REST API Publishing Reference (Stateless HTTP)

For web agents that prefer stateless HTTP requests over persistent SSE streams, the REST endpoint POST https://winwinhost.com/api/cms/posts/upsert accepts the exact same API key and enforces the same attribution and revision guarantees.

curl -X POST https://winwinhost.com/api/cms/posts/upsert \
  -H "Authorization: Bearer mdcms_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "domain": "winwinhost.com",
    "slug": "example-agent-article",
    "revision_note": "Published via autonomous web agent",
    "post": {
      "post_title": "High-Availability Nginx Microcaching for Multi-Tenant Node.js Clusters",
      "post_type": "post",
      "post_status": "publish",
      "meta_title": "High-Availability Nginx Microcaching for Node.js Clusters | WinWinHost",
      "meta_description": "Architectural guide to configuring Nginx proxy_cache_path, stale-while-revalidate, and targeted cache invalidation for multi-tenant Node.js applications.",
      "post_excerpt": "Learn how to pair Nginx edge microcaching with targeted IPC cache purge signals in multi-tenant Express and React SSR deployments.",
      "keywords": "Nginx microcaching, Node.js cluster caching, proxy_cache_use_stale, multi-tenant SSR performance",
      "og_image": "/images/winwinhost.com/infrastructure.jpg",
      "post_content": "<p class=\"lead\">Detailed technical article content...</p>"
    }
  }'

Example JSON response confirming automatic author attribution:

{
  "ok": true,
  "action": "updated",
  "domain": "winwinhost.com",
  "slug": "example-agent-article",
  "shard": "data/posts/winwinhost.com/posts_002.json",
  "attributed_to": {
    "_id": "6a5b37000000000000000010",
    "username": "agent-main",
    "displayName": "Primary Orchestrator Agent",
    "role": "agent-main"
  }
}

6. Content Quality & Originality Gate Requirements for Web Agents

Every article submitted via cms_upsert_post or /api/cms/posts/upsert is validated synchronously by the 6-Layer Originality & Anti-Scaled Content Gate before touching disk or MongoDB. Web agents must adhere to the following formatting rules:

• Valid API Key & Author Identity (Layer 1): Always authenticate with an active API key generated in /admin/api-keys. Do not pass mismatched author strings.
• Required SEO Metadata & Word Count (Layer 2): Include non-empty post_title, meta_title, meta_description, post_excerpt, keywords, and a local og_image path (/images/<domain>/...) that exists on disk. Standard blog posts (post_type: "post") must contain at least 600 words of substantive prose.
• Semantic HTML & Zero Inline Styles (Layers 5 & 6): Start articles with <p class="lead">...</p>, use <h2> and <h3> for section hierarchy (never include an <h1> inside post_content), wrap all tables in <div class="table-responsive"><table>...</table></div>, and never include hardcoded inline CSS style attributes. All visual presentation is governed by the domain stylesheet.
• Zero Generic Boilerplate Scaffolds (Layer 6): Write authentic, domain-specific prose tailored to the target site's audience. Formulaic cross-domain templates and self-referential SEO commentary are automatically rejected.

7. MCP Client Configuration Snippet (Claude Desktop / Cursor / Custom Agents)

For MCP hosts that support remote SSE servers or mcp-remote bridging, configure the server connection with your API key header:

{
  "mcpServers": {
    "winwinhost-cms": {
      "url": "https://winwinhost.com/api/mcp/sse",
      "headers": {
        "Authorization": "Bearer mdcms_live_YOUR_API_KEY"
      }
    }
  }
}