Skip to content
satware® AI OnlyOffice MCP

Architecture

Overview

Section titled “Overview”

The satware® AI OnlyOffice MCP server is a single Express application that serves the Model Context Protocol, an admin UI, artifact downloads, and health checks all on one port.

Single-Port Model

Section titled “Single-Port Model”

One Express app on port :3847 serves five endpoints:

Endpoint Method Purpose
/mcp POST MCP Streamable HTTP transport (protocol 2025-11-25)
/admin GET Vue 3 + Element Plus admin SPA (session-cookie auth)
/artifacts GET Document artifact downloads (auto-cleaned)
/health GET Service health status (JSON)
/instances GET OnlyOffice instance list + health

TLS termination is handled by a reverse proxy (Caddy or Nginx) in production.

Docker Stack

Section titled “Docker Stack”
+-------------------------------------------------------------+
|                    Docker Compose Stack                      |
+-------------------------------------------------------------+
|  +------------------+  +------------------+  +-------------+ |
|  |   MCP Server     |  |   OnlyOffice     |  |  Artifact   | |
|  |   Port: 3847     |--|   Port: 9980     |  |   Cleanup   | |
|  | /mcp /admin      |  |   (Document      |  |  (Cron)     | |
|  | /artifacts       |  |    Builder)      |  |             | |
|  | /health          |  |                  |  |             | |
|  +--------+---------+  +------------------+  +------+------+
|           |                                     |          |
|           +----------- /var/artifacts ----------+          |
+-------------------------------------------------------------+

Services

Section titled “Services”
Service Base Image Port Purpose
mcp-server node:25-slim (multi-stage) 3847 MCP server + admin UI + artifact downloads
onlyoffice onlyoffice/documentserver 9980 (internal) Document generation engine
artifact-cleanup alpine:3.20 + supercronic - Removes expired artifacts (configurable TTL)

Optional services (enabled via Docker Compose profiles):

Profile Service Use Case
s3 minio S3-compatible storage for development
smb samba SMB/CIFS share for development

Tool Flow

Section titled “Tool Flow”

When an AI agent calls onlyoffice_generate_document:

AI Agent
  |
  | MCP tool call (stdio or HTTP)
  v
MCP Server (Express :3847)
  |
  | 1. Validate data against template schema (Zod)
  | 2. Generate DocBuilder script from template + data
  | 3. Execute script in OnlyOffice container via Docker exec
  v
OnlyOffice Document Server (:9980)
  |
  | 4. Render document (DOCX/PPTX/XLSX)
  | 5. Optional: Convert to PDF
  v
MCP Server
  |
  | 6. Store artifact to /var/artifacts
  | 7. Return download URL or base64 to agent
  v
AI Agent

Multi-Instance Support

Section titled “Multi-Instance Support”

The server supports multiple OnlyOffice Document Server instances for load balancing or tenant isolation. Configure via the ONLYOFFICE_INSTANCES environment variable (JSON) or the admin UI at /admin/instances.

Each tool accepts an optional instanceId parameter to target a specific instance. If omitted, the default instance is used.

Admin UI

Section titled “Admin UI”

The admin interface at /admin provides:

  • Templates: List, create, edit, delete. Upload DOCX files and auto-extract JSON schemas from placeholders. Fill forms to generate documents.
  • Artifacts: List and delete generated document artifacts.
  • Credentials: Create, edit, and delete encrypted cloud storage credentials (Google Drive, OneDrive, S3, MinIO, WebDAV, SMB).
  • Instances: Full CRUD for OnlyOffice instances. Health checks, set default, reload registry.

Authentication is via a session cookie (HMAC-SHA256 signed, 8h lifetime). Set ADMIN_PASSWORD to enable. If unset, /admin returns 503.

Section titled “Related”