MCP

Der primedocs MCP Server stellt primedocs-Funktionen über das Model Context Protocol (MCP) für KI-Agenten bereit, etwa für Microsoft 365 Copilot oder andere MCP-fähige Assistenten. Damit können Agenten Vorlagen suchen, deren Eingabestruktur abfragen und Dokumente generieren, ohne die primedocs-Oberfläche zu öffnen.

hinweis

Die Dokumentation der Vorlagenoptimierung für Microsoft 365 Copilot (PowerPoint, Word, Outlook, Excel) findet sich neu unter Best Practices und Anwendungsfälle › Microsoft 365 Copilot. Diese Seite beschreibt den MCP-Server als Schnittstelle.

Architektur

Der MCP Server ist eine eigenständige Anwendung (PrimeDocs.Web.Mcp) und wird getrennt vom übrigen primedocs-Server betrieben. Er nutzt einen statuslosen HTTP-Transport, sodass keine Sitzungszustände gehalten werden.

Der MCP-Endpunkt ist mandantenspezifisch und enthält die Datasource-ID im Pfad:

POST https://{instanz}/mcp/{datasourceId}

Der Pfad setzt sich aus der Basis-URL der MCP-Anwendung (in der Standardinstallation /mcp) und der Datasource-ID zusammen.

Die {datasourceId} ist die GUID der Datasource, wie sie im id-Attribut des Datasource-Eintrags in der primedocs.config hinterlegt ist, und lässt sich auch aus der URL der DataSourceAdminApp (Dashboard) ablesen: Nach der Auswahl einer Datasource enthält jede Admin-URL den Parameter ?dataSource={datasourceId}.

Info-Seite

Die Basis-URL des MCP Servers liefert im Browser eine Info-Seite. Die Seite ist ohne Anmeldung erreichbar und eignet sich damit als schnelle Kontrolle, ob der Dienst läuft und welche Tools die laufende Instanz tatsächlich bereitstellt. Der Tool-Katalog wird zur Laufzeit aus dem Server gelesen, nicht aus einer statischen Liste.

Die Seite zeigt drei Bereiche:

Bereich	Inhalt
Server Info	Basis-URL, Transport, MCP-Endpunkt und Authentifizierungsverfahren
Tools	Anzahl der registrierten Tools sowie pro Tool Name, Beschreibung und das aufklappbare Eingabeschema (JSON)
Discovery Endpoints	Verweise auf die Metadaten-Endpunkte für die Authentifizierung

Authentifizierung

Der Server ist eine über OAuth 2.0 geschützte Ressource. Die Autorisierung erfolgt gegen den primedocs IdentityServer. Die Zugriffstoken werden serverseitig per Introspection validiert.

MCP-Clients ermitteln die Autorisierungsparameter automatisch über die Discovery gemäss MCP-OAuth-Spezifikation. Die Metadaten liegen unterhalb der Basis-URL der MCP-Anwendung:

GET https://{instanz}/mcp/.well-known/oauth-protected-resource

Die Antwort liefert die geschützte Ressource, den zuständigen Autorisierungsserver (IdentityServer) sowie den benötigten Scope. Bei einem 401 antwortet der Server zusätzlich mit einem WWW-Authenticate-Header, der auf die Resource-Metadaten verweist. Das Token wird als Bearer-Token im Authorization-Header gesendet.

MCP-Client registrieren

Die Metadaten des Autorisierungsservers verweisen auf den Client-Registrierungsendpunkt. Beide liegen wie die übrigen Metadaten unterhalb der Basis-URL der MCP-Anwendung:

GET  https://{instanz}/mcp/.well-known/oauth-authorization-server
POST https://{instanz}/mcp/oauth/register

Vor der Registrierung müssen die Callback-URLs des MCP-Clients als redirect_uris feststehen. Jeder angegebene URI muss eine der folgenden Regeln erfüllen:

• HTTP-Loopback-Callbacks auf 127.0.0.1, localhost oder [::1] mit einem der Pfade /, /callback, /oauth/callback oder /oauth/callback/debug. Nur der Port darf abweichen. Schema, Host, Pfad, Query, Fragment und Benutzerinformation müssen übereinstimmen. Andere Adressen aus 127.x.x.x und HTTPS-Loopback-Callbacks werden abgelehnt.
• Der im Attribut redirectUri konfigurierte Wert des primedocs Client-Eintrags mit userAuthType="FromLoginForMcp" in der primedocs.config. Ist dieser Wert selbst ein HTTP-Loopback-URI, darf ebenfalls nur der Port abweichen. Andernfalls muss der angeforderte URI der Konfiguration zeichengetreu und unter Beachtung der Gross-/Kleinschreibung entsprechen.

Eine erfolgreiche Registrierung antwortet mit HTTP 201 und gibt die akzeptierten redirect_uris in der JSON-Antwort zurück. Fehlende, leere, fehlerhaft formatierte oder nicht erlaubte redirect_uris führen zu HTTP 400:

{
  "error": "invalid_redirect_uri",
  "error_description": "..."
}

Ein Anfragekörper, der kein gültiges JSON-Objekt ist, sowie ein client_name, der keine Zeichenfolge ist, führen zu HTTP 400 mit "error": "invalid_client_metadata". Weitere Registrierungsfelder wie grant_types oder response_types prüft der Endpunkt nicht. Er antwortet stattdessen mit den von ihm unterstützten Werten. Ist kein MCP-Client konfiguriert, antwortet der Endpunkt mit HTTP 503.

Geänderte Validierung

Die Redirect-URIs werden neu bereits bei der Registrierung geprüft. Ein Client, dessen Registrierung bisher durchlief, kann deshalb jetzt mit HTTP 400 abgewiesen werden. Die Fehlkonfiguration fällt damit sofort auf und nicht erst bei der Autorisierungsanfrage.

Verfügbare Tools

Der Server stellt aktuell folgende Tools bereit. Die Namen sind die Namen, unter denen MCP-Clients die Tools aufrufen. Die Info-Seite zeigt sie für die laufende Instanz.

Tool	Zweck	Hinweise an den Client
get_template_structure	Liefert die Formularhierarchie einer Vorlage inklusive Feldtypen, Pflichtkennzeichen und wiederholbaren Sammlungen (Collections).	nur lesend, wiederholbar
generate_document	Generiert ein Dokument, indem aus strukturierten Formularwerten eine Connect Session für die gewählte Vorlage erstellt wird.	schreibend, nicht wiederholbar
get_all_templates	Gibt alle für den Benutzer verfügbaren Vorlagen zurück.	nur lesend, wiederholbar
find_templates	Sucht Vorlagen anhand einer Suchanfrage.	nur lesend, wiederholbar

Die Hinweise sind als MCP-Tool-Annotationen hinterlegt (readOnlyHint, idempotentHint). Alle Tools sind als nicht destruktiv (destructiveHint: false) und als geschlossen gegenüber externen Systemen (openWorldHint: false) gekennzeichnet. MCP-Clients können diese Hinweise nutzen, etwa um vor einem schreibenden Aufruf eine Bestätigung einzuholen.

Server und Tools melden zudem das primedocs-Symbol (PNG, 196 × 196 Pixel) für die Anzeige im Client, sofern die URL der MCP-Anwendung in der primedocs.config hinterlegt ist. Das Symbol liegt unter {URL der MCP-Anwendung}/icon, in der Standardinstallation https://{instanz}/mcp/icon, und ist ohne Anmeldung abrufbar.

Nur getaggte Vorlagen werden gefunden

get_all_templates und find_templates liefern nur Vorlagen, die einen bestimmten Tag tragen. Welcher Tag das ist, wird serverseitig über das Attribut mcpTemplateTagName auf dem <openAi>-Element der primedocs.config festgelegt (siehe primedocs AI (Preview)). Ohne gesetztes Attribut bzw. ohne entsprechend getaggte Vorlagen geben die Tools nichts zurück.

Ein typischer Ablauf eines Agenten:

1. Vorlage finden: find_templates oder get_all_templates.
2. Eingabestruktur abfragen: get_template_structure liefert die erwarteten Felder.
3. Dokument generieren: generate_document mit den strukturierten Formularwerten.

info

generate_document erwartet Werte passend zur Struktur aus get_template_structure: JSON-Objekte für Objektfelder, Arrays für Collection-Felder und ISO-Datumsangaben (yyyy-MM-dd) für Datumsfelder.

hinweis

Die Installation und der Betrieb des MCP Servers (separate Anwendung, Reverse Proxy, IdentityServer-Anbindung) werden unter MCP Server beschrieben.