MCP setup
The CommsPliant MCP server lets an AI client work as a signed-in user. Letters it changes are the same records shown in the web application.
Production URL: https://adminapi.commspliant.com/mcp
Staging uses the staging admin API origin with the same /mcp path.
The authorization server stays on https://adminapi.commspliant.com. Access tokens are audience-bound to https://adminapi.commspliant.com/mcp.
Before a customer connects
- Apply database migrations
100_mcp_oauth_revisionand101_mcp_org_policy. The admin API applies them on startup. - Set a stable
OAUTH_SIGNING_KEY_PEMon the admin API. An empty value generates a key that changes on restart and disconnects every client. - Leave
PUBLIC_MCP_URLunset so it defaults to the admin API origin plus/mcp. Set it only when that public URL is different. - In the admin application, open MCP server. Turn on Included in plan and Enabled. Leave Read-only off only when the organisation should allow edits.
An organisation that is not entitled, or not enabled, receives 403 with mcp_not_entitled or mcp_disabled.
Connect a client
- Add the MCP server URL in the client. For production that is
https://adminapi.commspliant.com/mcp. - Choose OAuth. The server advertises PKCE S256, protected-resource metadata, and dynamic client registration.
- Sign in, complete MFA when it is required, choose the organisation, and authorise the scopes.
- For a server-to-server test, send the organisation API key as
Authorization: Bearer ck_...instead of completing OAuth. The key is still bound to that one organisation.
ChatGPT, Claude, and Cursor can use this URL. Directory listings are published after a staging organisation completes the acceptance path.
Security note
- The connection acts as the person who authorised it, with that person's permissions and one organisation. It cannot read another tenant.
- Draft edit, submit, and delete stay author-only. A colleague receives
403not_version_author. - Approval stays a different person with
template.approve. The AI connection cannot approve its own draft. - Credentials stay in the OAuth or API-key header. Tool arguments and audit summaries do not contain tokens or raw letter HTML.
- Audit rows record the user, organisation, client name, tool, a short input summary, and
result: accepted. - Usage is counted per organisation, tool, and day for billing. Per-token and per-organisation limits return
429withRetry-After. - Document bytes are processed by the admin API. MCP does not keep a separate copy.
- Tool names in set
2026-10-14stay stable. A removed tool is marked deprecated for one version before it disappears.
Protected resource metadata is published at https://adminapi.commspliant.com/.well-known/oauth-protected-resource/mcp.