app.communicationos-mcp

CommunicationOS MCP

Governed Model Context Protocol surface for CommunicationOS. It exposes tenant-scoped thread reads, drafting, summarization, extraction, provider health, inbound-route inspection, and the canonical Forms operation registry. Forms tools inherit their contract auth and PII annotations. Direct communication.reply.send is intentionally excluded: outbound delivery remains subject to room membership, current authority, and the approval/send orchestrator.

MailerSend diagnostics

createMailerSendMcpProviderDependencies binds the read-only integrations.email.provider.health and integrations.email.inbound-routes.list tools. The host injects a tenant-and-connection-scoped resolver returning MailerSend credentials and a domain id. Secrets never appear in MCP tool inputs or outputs.

Both tools take tenantId as input, but they only run for the verified subject (src/provider-scope.ts). The input tenant must equal the subject's tenantId, and the subject must hold the admin role, because the contracts declare policy.auth: 'admin' and the MCP gate itself only checks for an authenticated actor. Anything else is FORBIDDEN (403) before the connection resolver is called, so a token for one tenant can never load another tenant's MailerSend connection.

Subject and trust boundary

The stdio entrypoint (startCommunicationOsMcpServer) verifies one CommunicationOS access token at startup with createCommunicationAccessTokenVerifier from @lssm-tech/integration.communication-os-host-auth, then builds the server. It reads only these variables:

A verified, in-scope token becomes the subject of every tool call: { actor: 'user', userId: <principalId>, tenantId, workspaceId, roles }, with the token's space as the policyContext.spaceId fact. Handlers and policies therefore see the verified workspace and space, not only the tenant. The principal and the token's exp are cached; from exp onward, and whenever a variable is missing or the secret, signature, issuer, audience, scope or expiry does not verify, every call is anonymous and the MCP auth gate rejects it. The startup log line reports subject: authenticated | unconfigured | rejected and never the token. Restart the gateway with a fresh token to renew it.

Trust boundary. Verifying the token needs the shared HS256 secret, which can also mint tokens. Run this gateway only server-side, next to communicationos-api and inside its secret boundary, never on a client or developer machine. Distributing it to clients would need a contract-first token introspection route instead of the shared secret.

The import-time server export and buildCommunicationOsMcpServer() without a resolver stay anonymous. startCommunicationOsMcpServer builds and connects its own gateway after verification, so the exported server is not the connected instance. The default server binds no provider resolver, so production hosts must also inject a vault-backed connection resolver before the provider tools can execute; the subject guard above still applies.