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

  1. Apply database migrations 100_mcp_oauth_revision and 101_mcp_org_policy. The admin API applies them on startup.
  2. Set a stable OAUTH_SIGNING_KEY_PEM on the admin API. An empty value generates a key that changes on restart and disconnects every client.
  3. Leave PUBLIC_MCP_URL unset so it defaults to the admin API origin plus /mcp. Set it only when that public URL is different.
  4. 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

  1. Add the MCP server URL in the client. For production that is https://adminapi.commspliant.com/mcp.
  2. Choose OAuth. The server advertises PKCE S256, protected-resource metadata, and dynamic client registration.
  3. Sign in, complete MFA when it is required, choose the organisation, and authorise the scopes.
  4. 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 403 not_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 429 with Retry-After.
  • Document bytes are processed by the admin API. MCP does not keep a separate copy.
  • Tool names in set 2026-10-14 stay 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.