communications-access-broker

Communications MCP access broker: tiered, human-gated chat access to Matrix and Microsoft Teams, built on access-broker-core. Fourth broker in the suite.

Why access brokers

The Model Context Protocol connects AI agents to real infrastructure: file stores, chat platforms, mail servers, a home. Its permission model is static. An MCP server declares a list of tools; the client shows the list to the user once, at install time; the user approves; from then on, every tool call runs with the server's full credential.

The model cannot express what matters once the infrastructure is real.

• A grant is all-or-nothing at install time. There is no scoped, expiring grant for one folder, one room, or one lock. Approving the server approves everything it can reach.

• There is no per-operation review. After install, a destructive write runs as freely as a harmless read.

• There is no audit of agent decisions. What the agent requested, what was refused, and who approved what is recorded nowhere the owner controls.

• There is no human gate for sensitive actions. The only approval happened between the agent and the client, before any concrete operation existed.

• The credential at the server carries everything the server can do. Tool descriptions that promise restraint are advisory; the token is not.

An access broker is an MCP server that closes these gaps for one domain. It holds the real credential, exposes a deliberately small tool surface, and turns access into an explicit object: a scoped, expiring, audited, human-approved grant, evaluated per operation.

Related MCP server: NetGram

The access broker model

The suite implements one model with seven properties. Every broker carries all of them; the mechanics live in access-broker-core.

1. A tier model per domain. Every operation is classified before it can be requested. T0/T1 are free-lane reads and reversible actions that run without a grant. T2 operations are sensitive and require per-operation human approval through an approval gateway on a chat platform; the agent cannot self-approve, and batches do not exist. T3 operations are always gated and, where the action is irreversible, are never offered as tools at all.

2. Declared operations. Each tool names the operation it performs. The wall, the broker's scope checker, validates the resource and the operation against active grants before anything executes. The free lane is defined by the domain tier table, not by what happens to be exposed.

3. Write-before-operate, hash-chained audit. Every request, execution, refusal, and human decision is an audit-class event written to a hash-chained log before the operation runs. verify_chain detects tampering, including truncation. The chain, not memory, is the record of what the agent did and why.

4. Fail-closed everywhere. Any configuration or validation failure refuses the boot. Unknown or malformed input denies. A restart never widens capability and never promotes pending or suspended state.

5. Approval separation. The approval gateway account is never a brokered account. A broker that could approve its own requests is a design failure, and the configuration is refused at boot.

6. Custody declarations. The broker declares, machine-readably, what its backend credentials can reach. An undeclared trust boundary refuses to start, and the custody class rides every audit record.

7. The D5 two-surface model in the data domain. The agent surface handles metadata and reasoning; bulk bytes move through a separate transfer surface addressed only by a CLI holding its own token, with SHA-256 verify-then-write. File content never enters LLM context.

The suite

access-broker-core carries the mechanics: the grant store (conditional-SQL CAS state machine), policy wall evaluation, the hash-chained audit log, the approval-gateway substrate, the custody registry, the baseline engine, and transport authentication. Each broker is a thin domain layer: a scope-checker wall, backend adapters, a tier table, and tool surfaces. One repo per broker; no monorepo.

What it is

One MCP server brokering an AI agent's access to chat platforms. The broker holds a dedicated Matrix account's token and a Teams delegated Graph token; the agent never sees either. It contributes the communications wall (room scoping), the Matrix (matrix-nio) and Teams (Graph delta-polling) backends, and the enforcement that gives approval separation teeth for the first time in the suite: the brokered Matrix account must never be its own approval gateway, and a configuration where the two coincide refuses the boot (check_approval_separation).

The tier model for conversation

• No free reads. Conversation content is surveillance-grade; reads are grant-scoped per room, full stop. A read without an active grant naming the room is refused. This is the one broker in the suite with no T0/T1 lane at all: the seventh suite property is data-domain, and this domain's analogue goes the other way, everything is grant-scoped because everything a room contains is private by default.

• T2 gated, per operation (no batches): send, reply, react, edit-own. Messages have no version history and no trash; per- operation approval is the compensating-control argument.

• T3 gated, never offered: redaction, deletion, bulk operations, membership changes, moderation. No v1 tool form reaches them; a moderation function that cannot be revoked after the fact does not become a tool.

• No wildcards. Grants name rooms exactly; room aliases resolve at the backend boundary, never in the wall.

• E2EE fails closed. Encrypted rooms are detected and refused at the backend boundary; key custody is a fast-follow with its own review.

• One discovery exception: list_spaces. The account-scoped @spaces read (room ids, names, joined/invited state) is the surface's single free read — audited like every executed op, never content. Registered only when the deployment enables discovery (discovery: true, the default; false removes the tool at registration time). Everything else in the tier table is unchanged: a grant-less content read is refused, never approvable by call.

Tool surface: get_history, get_room_state, get_members (reads, grant-scoped per room; each preflighted — an invisible room refuses with the real reason, never a silent empty payload), send_message, reply, react, edit_own (each individually human-approved), plus request_access, check_access, revoke_access, list_accounts, and list_spaces (discovery; see the exception above).

Production-alpha notes

Live-verified 2026-09-21/22 through the owner's native MCP client (discovery → request → approval → grant → read/send → read-back).

• Approval-plane shield. execute() and request_access refuse ANY operation on the gateway's own approval room, before the wall: the brokered identity cannot request access to the room that approves it. The shield beats active grants and rides protected_surfaces from the gateway config.

• Membership preflight. Every content read (get_history, get_room_state, get_members) verifies the caller's own membership first: homeservers answer reads on invisible rooms with an HTTP-200 empty payload, and the preflight turns that into a refusal with the real reason.

• T2 grant semantics (open, owner decision pending). An approved T2 grant currently carries a time window, while the historical wording promises per-operation approval every time. No consume-on-use path exists in v1. Resolution options on record: execute-time self-revocation after a gated op fires (true one-shot) or a docstring correction to match the window semantics. Until the owner decides, treat an approved T2 grant as a time window and audit it accordingly (grant-level revocation is available agent- and owner-side).

• Known cosmetic gaps (queued). Pending-request dedupe (repeated requests stack new numbers), the ops comma-string parameter shape, and pre-approval validation of gated-op targets.

What is NOT here (v1)

Email (never here; drafts and store-and-forward are the groupware broker's domain), Telegram and Signal (v2), encrypted rooms, voice (deferred hard: no draft artifact, no revision point), raw user-API Telegram reads (ToS-sensitive). File storage is the data broker's domain; PIM is groupware's; entities are the automation broker's.

Status

Production alpha (owner-verified live 2026-09-22 through the native MCP client; see the notes above). 327 tests across nine files, 100% statement and branch on every module; the real-protocol battery runs against a scratch Dendrite. See CHANGELOG.md and DEPLOYMENT.md (including the user-space systemd supervision section). Repository publication: Sourcehut canonical, owner-gated.

Security

SECURITY.md carries the domain threat model: the primary adversary is the conversation content itself (a planted prompt injection in any granted room is inside the agent's trust boundary), the secondary is the irreversibility of sent messages, the tertiary is the approval plane. Custody classes are declared per backend (matrix: account-wide; teams: scoped under the employer app registration). The suite invariants are stated once in the core README and inherited here.

Provenance

Author and maintainer: Nasser Mohieddin Abukhdeir. The primary implementation model was GLM (glm-5.3), with glm-5.3-flash as the delegated sub-agent model. See AUTHORS.md for the full provenance record.

License

GPL-3.0-or-later.