app.communicationos-mcp
MCP server exposing CommunicationOS contracts as AI-callable tools via the Model Context Protocol.
@lssm-tech/app.communicationos-mcpbun add @lssm-tech/app.communicationos-mcpManifest declarations describe the current workspace; they do not verify registry publication or runtime execution.
Package guide
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:
| Variable | Purpose |
|---|---|
COMMOS_MCP_ACCESS_TOKEN | Access token minted by communicationos-api (issuer https://api.hcircle.app, audience communication-os-api). |
COMMOS_MCP_TENANT_ID, COMMOS_MCP_WORKSPACE_ID, COMMOS_MCP_SPACE_ID | The scope the token must carry exactly. |
COMMUNICATION_OS_ACCESS_TOKEN_SECRET | The shared HS256 signing secret (at least 32 bytes). |
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.
Managed CompanyOS composition
When the managed CompanyOS ecosystem launches the gateway it sets COMMOS_MCP_HOST_ASSERTION instead of an access token, and the entrypoint uses composeManagedCommunicationOsMcpGateway (src/managed-composition.ts). The assertion is a short-lived CompanyOS host assertion for exactly the configured COMMOS_MCP_TENANT_ID, COMMOS_MCP_WORKSPACE_ID and COMMOS_MCP_SPACE_ID. The gateway exchanges it with the CommunicationOS host-session exchanger that communicationos-api uses, then verifies the issued token through the standalone subject resolver and builds the same governed gateway. It reads only these extra variables:
| Variable | Purpose |
|---|---|
COMMOS_MCP_HOST_ASSERTION | CompanyOS host assertion (audience https://api.hcircle.app/v2/auth/host-exchange). |
COMMUNICATION_OS_COMPANYOS_ISSUER, COMMUNICATION_OS_COMPANYOS_SHARED_SECRET | The only accepted assertion issuer and its HS256 secret (at least 32 bytes). |
COMMUNICATION_OS_HOST_MEMBERSHIPS | JSON array of explicit { issuer, subject, tenantId, workspaceId, spaceId } tuples, as in communicationos-api. |
An assertion from another issuer, secret or scope, a subject without an exact membership tuple, or a missing or malformed membership policy leaves the gateway anonymous (subject: rejected | unconfigured), so every tool call fails closed. The startup log line reports hosting: managed.
Session lifetime. The exchanger issues the access token with its default 5-minute lifetime, and the assertion itself expires after 60 seconds. The managed session therefore lasts 5 minutes from launch; from then on every tool call is anonymous and fails closed. There is no refresh path: the CompanyOS host must relaunch the gateway with a fresh assertion.
Trust model. This is not an independent authorization boundary in the way the communicationos-api exchange is. The process holds the CompanyOS assertion secret as well as the access-token secret, and the membership policy comes from the same launch environment as the assertion. Only COMMOS_MCP_HOST_ASSERTION and the COMMOS_MCP_*_ID scope may be per-launch input. COMMUNICATION_OS_HOST_MEMBERSHIPS, COMMUNICATION_OS_COMPANYOS_ISSUER and both secrets must come from operator-controlled deployment configuration, never from per-launch host input. The assertion carries communicationos-api's host-exchange audience, so treat the launch environment as secret: a leaked assertion can be replayed at communicationos-api until it expires (60 seconds). The standalone trust boundary above still applies: run the gateway only server-side, inside the CommunicationOS secret boundary.
Relationships
Arrows point from a package to its direct dependency. Counts are derived from captured workspace manifests.
11 declarations
@lssm-tech/lib.communication-specworkspace:^
Read the package manual ↗@lssm-tech/lib.contracts-integrationsworkspace:^
Read the package manual ↗@lssm-tech/lib.contracts-runtime-server-mcpworkspace:^
Read the package manual ↗@lssm-tech/lib.contracts-specworkspace:^
Read the package manual ↗@lssm-tech/lib.decision-runtimeworkspace:^
Read the package manual ↗@lssm-tech/lib.loggerworkspace:^
Read the package manual ↗
Declared capabilities
This manifest does not declare a capability catalogue. Use the guide, import map and source to assess the package.
Scripts
startbun src/index.tstypechecktsgo --noEmitlint:checknode ../../../scripts/biome.cjs check .lintbun run lint:fixlint:fixnode ../../../scripts/biome.cjs check --write .