Content.One MCP Remote Server

The Content.one MCP Remote Server implements MCP over HTTP using the @modelcontextprotocol/sdk. It functions as a secure gateway between MCP clients and Content.one instance APIs so tools and LLMs can fetch instance-specific context when generating content or answering prompts.

• Stateless authentication via Bearer tokens (per-request).
• Extensible tools surface instance resources: content, media, models, labels, settings, etc.
• Integrates with monitoring (Sentry) and supports streaming JSON‑RPC responses.

POST /mcp — main MCP entrypoint. Accepts JSON‑RPC 2.0 requests (MCP messages) and returns JSON‑RPC 2.0 responses.

Headers

• Authorization: Bearer <SESSION_TOKEN> (required)
• Content-Type: application/json
• X-Instance-Zuid: <INSTANCE_ZUID> (optional — enables instance-scoped tools)

Body

A valid JSON‑RPC 2.0 request object. Example:

{
  "jsonrpc": "2.0",
  "method": "tools/list",
  "params": {},
  "id": 1
}

Authentication is stateless: clients present a session token each request. The server verifies the token (via Content.one session verification or an auth adapter) and returns an error for invalid tokens.

Tip: protect session tokens in transit (HTTPS) and limit token scope/TTL where possible.

REST endpoints under /api/chats that store the AI drawer’s conversation history per user and instance. See the API documentation for every route, its parameters, responses and errors.

• GET /api/chats — List the user’s chats
• POST /api/chats — Create a chat
• GET /api/chats/:chatZuid — Get a chat with its prompts
• POST /api/chats/:chatZuid/prompt — Add a prompt
• PATCH /api/chats/:chatZuid/prompt/:promptZuid — Update a prompt’s approval

POST /client generates content for the AI drawer with Gemini, using this server's MCP tools in-process. It returns UI actions the editor can apply and, optionally, saves the exchange to chat history.

Headers

• Authorization: Bearer <SESSION_TOKEN> (required)
• Content-Type: application/json (required)
• X-Instance-Zuid: <INSTANCE_ZUID> — enables the MCP tools, editor context and chat history. Without it, text prompts are answered without tools, image prompts return the raw image bytes, and block prompts return 400.

Prompt routing

Each prompt is routed by keyword to one of three flows:

• Image — "generate an image", "draw", "illustrate", "paint", "image"… Generates an image with gemini-2.5-flash-image, uploads it to the instance's media bin, and returns actions that set it on an image field.
• Block — "block", "web component". Creates a block (model, fields and code) in the instance.
• Text — anything else. Answers with the editor context, calling MCP tools when needed (up to 5 turns).

Body

• prompt (required) — the user's request; a string or an array of strings.
• systemInstruction, temperature — extra instructions and randomness (default 1.0).
• tone, language, registryKeys, refRegistry, modelZuid, itemZuid — the content item being edited and the fields the response may fill.
• code, filename, fields — code editor context; when code is sent, responses target the code editor.
• url — the Manager UI URL. Sending it turns on chat history saving.
• chatZuid — continue an existing chat; its past exchanges are sent to the model as the conversation so far.
• roleZuid — required to start a new chat (url without chatZuid).

Response

{
  "data": [
    { "type": "SET_VALUE", "payload": { "refKey": "title", "value": "..." } },
    { "type": "SYSTEM_OUTPUT", "payload": { "value": "Message to the user" } }
  ],
  "message": "Generated text content using Gemini",
  "chatZuid": "51-...",
  "chatError": "Chat was not created: missing required field 'roleZuid'"
}

• data is always an array of UI actions: SET_VALUE fills a field (refKey; code-editor for code), SYSTEM_OUTPUT is a message, and the block flow adds NAVIGATE with the new block's path.
• chatZuid is the chat the exchange was saved to (empty when nothing was saved).
• chatError appears only when saving failed. The answer is still returned with status 200.
• The chats themselves are managed through the Chats API.

Text generation: gemini-2.5-flash

Image generation: gemini-2.5-flash-image

Use lower temperature for deterministic outputs and higher for creative output.

Listing tools (JSON-RPC)

curl -X POST https://mcp.content.one/mcp \
  -H "Authorization: Bearer $SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"tools/list","params":{},"id":1}'

Text generation (client)

curl -X POST https://mcp.content.one/client \
  -H "Authorization: Bearer $SESSION_TOKEN" \
  -H "X-Instance-Zuid: $INSTANCE_ZUID" \
  -H "Content-Type: application/json" \
  -d '{"prompt":"Write a tagline for this page","registryKeys":["title"],"temperature":0.6}'

Starting and continuing a chat (client)

# First prompt: url + roleZuid start a new chat; the response includes its chatZuid
curl -X POST https://mcp.content.one/client \
  -H "Authorization: Bearer $SESSION_TOKEN" \
  -H "X-Instance-Zuid: $INSTANCE_ZUID" \
  -H "Content-Type: application/json" \
  -d '{"prompt":"My name is Matt","url":"https://$INSTANCE_ZUID.manager.zesty.io/content","roleZuid":"$ROLE_ZUID"}'

# Follow-up: send the chatZuid back so the model sees the conversation so far
curl -X POST https://mcp.content.one/client \
  -H "Authorization: Bearer $SESSION_TOKEN" \
  -H "X-Instance-Zuid: $INSTANCE_ZUID" \
  -H "Content-Type: application/json" \
  -d '{"prompt":"What is my name?","url":"https://$INSTANCE_ZUID.manager.zesty.io/content","chatZuid":"$CHAT_ZUID"}'

• Always use TLS (HTTPS) to protect tokens and responses in transit.
• Validate and scope session tokens server-side; apply least privilege.
• Sanitize and limit tool outputs before feeding them into LLM prompts.
• Rate-limit MCP calls and monitor usage.