MCP

The primedocs MCP server exposes primedocs capabilities to AI agents through the Model Context Protocol (MCP) — for example to Microsoft 365 Copilot or other MCP-capable assistants. Agents can search templates, query their input structure, and generate documents without opening the primedocs UI.

note

Guidance on optimising templates for Microsoft 365 Copilot (PowerPoint, Word, Outlook, Excel) now lives under Best Practices › Microsoft 365 Copilot. This page describes the MCP server as an interface.

Architecture

The MCP server is a standalone application (PrimeDocs.Web.Mcp) and runs separately from the rest of the primedocs server. It uses a stateless HTTP transport, so no session state is retained.

The MCP endpoint is tenant-specific and carries the datasource id in the path:

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

The path is composed of the base URL of the MCP application — /mcp in a standard installation — plus the datasource id.

The {datasourceId} is the GUID of the datasource, as stored in the id attribute of the datasource entry in primedocs.config. It can also be read from the DataSourceAdminApp (Dashboard) URL: after selecting a datasource, every admin URL contains the ?dataSource={datasourceId} parameter.

Info page

Opening the MCP server's base URL in a browser returns an info page. It is reachable without signing in and therefore serves as a quick check of whether the service is running and which tools the running instance actually provides — the tool catalog is read from the server at runtime, not from a static list.

The page shows three areas:

Area	Content
Server Info	Base URL, transport, MCP endpoint and authentication method
Tools	The number of registered tools plus, per tool, its name, description and the expandable input schema (JSON)
Discovery Endpoints	Links to the metadata endpoints for authentication

Authentication

The server is an OAuth 2.0 protected resource. Authorisation is performed against the primedocs IdentityServer; access tokens are validated server-side via introspection.

MCP clients discover the authorisation parameters automatically through the discovery endpoint defined by the MCP OAuth specification. The metadata lives below the base URL of the MCP application:

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

The response returns the protected resource, the responsible authorisation server (IdentityServer), and the required scope. On a 401 the server additionally returns a WWW-Authenticate header pointing to the resource metadata. The token is sent as a bearer token in the Authorization header.

Register an MCP client

The authorisation-server metadata points to the client registration endpoint. Like the other metadata, both live below the base URL of the MCP application:

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

Before registration, determine the MCP client's callback URLs to send as redirect_uris. Every supplied URI must satisfy one of the following rules:

• HTTP loopback callbacks on 127.0.0.1, localhost, or [::1] with one of the paths /, /callback, /oauth/callback, or /oauth/callback/debug. Only the port may differ; scheme, host, path, query, fragment, and user information must match. Other addresses in 127.x.x.x and HTTPS loopback callbacks are rejected.
• The value configured in the redirectUri attribute of the primedocs client entry with userAuthType="FromLoginForMcp" in primedocs.config. If this value is itself an HTTP loopback URI, only the port may differ. Otherwise, the requested URI must match the configured string character for character, including case.

A successful registration returns HTTP 201 and echoes the accepted redirect_uris in the JSON response. Missing, empty, malformed, or disallowed redirect_uris return HTTP 400:

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

A request body that is not a valid JSON object, and a client_name that is not a string, return HTTP 400 with "error": "invalid_client_metadata". The endpoint does not validate further registration fields such as grant_types or response_types — it responds with the values it supports instead. If no MCP client is configured, the endpoint returns HTTP 503.

Changed validation

Redirect URIs are now checked at registration time. A client whose registration used to succeed may therefore now be rejected with HTTP 400 — the misconfiguration surfaces immediately instead of during the authorisation request.

Available tools

The server currently exposes the following tools:

Tool	Purpose
GetTemplateStructure	Returns the template form hierarchy including field types, required flags, and repeatable collections.
GenerateDocument	Generates a document by creating a Connect Session from structured form values for the selected template.
GetAllTemplates	Returns all templates available to the user.
FindTemplates	Finds templates based on a search query.

Only tagged templates are found

GetAllTemplates and FindTemplates return only templates carrying a specific tag. Which tag is configured server-side via the mcpTemplateTagName attribute on the <openAi> element of the primedocs.config (see primedocs AI (Preview)). Without the attribute set — or without correspondingly tagged templates — the tools return nothing.

A typical agent flow:

1. Find a template — FindTemplates or GetAllTemplates.
2. Query the input structure — GetTemplateStructure returns the expected fields.
3. Generate the document — GenerateDocument with the structured form values.

info

GenerateDocument expects values matching the structure from GetTemplateStructure: JSON objects for object fields, arrays for collection fields, and ISO dates (yyyy-MM-dd) for date fields.

note

Installation and operation of the MCP server (standalone application, reverse proxy, IdentityServer integration) are described under MCP Server.