MCP Server

The Cuddler MCP Server is the MCP endpoint for schema-aware document generation against Cuddler v1.0.0-draft.6. It helps AI agents produce data instances that align with the selected Document Template schema before validation and export.

What This Is (and Is Not) in Draft 6

Data-first scope: Cuddler v1 draft 6 defines document data contracts and Document Template schema authoring requirements, not renderer runtime APIs.
Schema-first generation: MCP usage should produce a candidate JSON instance that is then validated against JSON Schema Draft 2020-12 plus Cuddler semantic checks.
No silent fallback rule: if validation fails, downstream exporters must fail clearly and must not emit normal output as if valid.
Version lockstep: generated instances must align meta.documentTypeId and meta.schemaVersion with the selected Document Template schema and its declared output metadata.

Recommended Workflow

Step	Action	Result
1	Select a document type and version from the Schema Catalog.	Target Draft 6 data contract identified.
2	Generate JSON with your MCP-enabled AI agent.	Candidate Cuddler document instance.
3	Validate against the selected Document Template schema and required semantic checks.	Deterministic pass/fail validity result.
4	Only after a successful validation pass, send the instance to your exporter/render pipeline.	Safe downstream processing with no contract drift.

Access and Authentication

MCP endpoint:

https://mcp.cuddler.dev

A Personal access token is required.
Create/manage tokens at http://subscription.cuddler.dev/personal-access-tokens.
Authenticate with an HTTP bearer token header: Authorization: Bearer <YOUR_CUDDLER_PAT>.
Treat PATs as secrets, rotate regularly, and avoid committing them to source control.

Add to Codex CLI

Codex CLI supports streamable HTTP MCP servers directly.

# PowerShell (current shell session)
$env:CUDDLER_PAT = "<YOUR_CUDDLER_PAT>"

# Add Cuddler MCP server
codex mcp add cuddler --url https://mcp.cuddler.dev --bearer-token-env-var CUDDLER_PAT

# Verify
codex mcp list

Codex config reference (equivalent):

[mcp_servers.cuddler]
url = "https://mcp.cuddler.dev"
bearer_token_env_var = "CUDDLER_PAT"

Add to Gemini CLI

Gemini CLI supports MCP server registration from the command line.

# PowerShell (current shell session)
$env:CUDDLER_PAT = "<YOUR_CUDDLER_PAT>"

# Add remote HTTP MCP server with auth header
gemini mcp add --transport http cuddler https://mcp.cuddler.dev --header "Authorization: Bearer ${CUDDLER_PAT}"

# Verify
gemini mcp list

Add to Copilot CLI

Copilot CLI can add MCP servers interactively or via JSON config.

Interactive

copilot
/mcp add cuddler http https://mcp.cuddler.dev
# when prompted for headers:
# Authorization: Bearer <YOUR_CUDDLER_PAT>
/mcp show

Config File

Add this to ~/.copilot/mcp-config.json (or pass as session config with --additional-mcp-config):

{
  "mcpServers": {
    "cuddler": {
      "type": "http",
      "url": "https://mcp.cuddler.dev",
      "headers": {
        "Authorization": "Bearer <YOUR_CUDDLER_PAT>"
      },
      "tools": ["*"]
    }
  }
}

copilot --additional-mcp-config @cuddler.mcp.json

Security Notes

Use dedicated PATs for MCP integrations rather than reusing credentials across systems.
Restrict token distribution to trusted developer environments and CI secrets stores.
If a token is exposed, revoke it immediately and create a replacement.