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 › 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:

Tool	Zweck
GetTemplateStructure	Liefert die Formularhierarchie einer Vorlage inklusive Feldtypen, Pflichtkennzeichen und wiederholbaren Sammlungen (Collections).
GenerateDocument	Generiert ein Dokument, indem aus strukturierten Formularwerten eine Connect Session für die gewählte Vorlage erstellt wird.
GetAllTemplates	Gibt alle für den Benutzer verfügbaren Vorlagen zurück.
FindTemplates	Sucht Vorlagen anhand einer Suchanfrage.

Nur getaggte Vorlagen werden gefunden

GetAllTemplates und FindTemplates 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 – FindTemplates oder GetAllTemplates.
2. Eingabestruktur abfragen – GetTemplateStructure liefert die erwarteten Felder.
3. Dokument generieren – GenerateDocument mit den strukturierten Formularwerten.

info

GenerateDocument erwartet Werte passend zur Struktur aus GetTemplateStructure: 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.