BoardAgent

BoardAgent is a self-hosted, MCP-native system of record for a board of directors. Each person on the board works through their own MCP-capable agent. BoardAgent has no human interface and runs no server-side AI. It stores the canonical machine-readable records and enforces procedure and authority on every operation. Every binding act is a human confirmation, and every event is hash-chained and signed.

A note from the human author

BoardAgent is the board portal of the future. It has no user interface. It accepts no PDFs, no Word documents, no PowerPoints. It only accepts machine-readable formats. A human cannot log in to the board portal. Only an agent can.

In fact, BoardAgent doesn't even have AI, because BoardAgent is a governance protocol for agents managing board workflows.

Each stakeholder (director, secretary, management, observers) talks to their own personal AI agent, whichever one they already use, and the agent talks to the board portal over MCP. They can then ask their agent to present the materials in whichever form they like (including PowerPoint, if they are stuck in 2020).

The board portal itself is a server of record: charter, seats, permissions, machine-readable papers, questions, votes, minutes, and a signed hash chain of everything that happened.

Today's board portals are document viewers with permissions and a black-box chatbot bolted on top. Board members are using an AI that they do not control or govern. A governance heresy, and a real risk for board members.

I think that in a few years (not that far away from now), they will be what this is: a protocol your own agent speaks, with the governance enforced on the server side where no model can talk its way past it. This is, in my view, what "AI-native" means.

I have a day job, so you will pardon me. The rest of this README file and the documentation is AI-generated. I have reviewed every word of it, but sorry if I hurt your feelings with AI-generated content.

Related MCP server: varco_mcp

Status

BoardAgent is an open-source beta. It is not production-ready, and it does not carry a security certification yet. I call this code line the private hardened beta: it passes its own regression net, except SR-102, which is still unresolved, and it has not passed an independent external review.

I built BoardAgent so that a board can keep its official records in one service that its members reach through the agents they already use, without handing those records to a shared assistant. Your agent presents information. BoardAgent records exact information and the confirmations you give. You remain responsible for reading what you confirm and for securing your agent and your local copies.

BoardAgent is not a qualified electronic-signature service or a notary yet, and it is not legal advice. It cannot yet prove that a person understood a record.

Binding confirmations need a client that renders forms

A binding act, such as a vote or an invitation, is confirmed through an MCP elicitation form. Your client must render that form; a client that only reads the board can browse it but cannot act on it. Today Claude Code renders these forms. Confirming in the browser with a passkey is the first item on the roadmap.

What it does

• Keeps one organization and its boards, members, governance profiles, rules, documents, meetings, transcripts, minutes, votes, proxies, questions, submissions, proposals and tasks in PostgreSQL.

• Applies role, board, recusal, confidentiality, lifecycle and exact-resource checks on every MCP operation.

• Requires a one-use, server-attested confirmation for every binding human act.

• Preserves append-only audit events, signed checkpoints, vote certificates, encrypted exports, backup receipts and restore receipts.

• Supports built-in WebAuthn and TOTP authentication, and pre-linked OIDC identities.

• Runs a separate least-privilege worker for notifications, exports, deadlines, checkpoints, cleanup of operational leftovers and recovery jobs.

What it deliberately does not do

• No server-side language models, embeddings, OCR, format conversion or content-check API.

• Only canonical Markdown, plain text and declared versioned JSON are accepted. PDF, PowerPoint, Word, images, scans, archives and binary redlines are rejected.

• No governance web UI and no email workflow. The browser is used for enrollment, authentication and onboarding attestation; board work happens in your MCP client.

• No physical purge of governance, content, audit, consent or evidence records in v1.

• Webhooks are contentless wake-ups. They are disabled by default and restricted against server-side request forgery.

• A software client name is not an identity. A deployment can restrict clients to exact server-issued client IDs or to exact client metadata URLs checked over HTTPS.

The frozen implementation contract is BUILD_PLAN.md. Security and trust boundaries are in SECURITY.md; deployment is in DEPLOY.md.

Architecture

MCP client / human browser
          |
       HTTPS
          |
        Caddy
          |
  BoardAgent server ---- public certificate verifier
          |
   private backend network
          |
      PostgreSQL <---- least-privilege worker
          |                      |
   audit/evidence          exports/notices/jobs

Operator CLI ---- migrations, bootstrap, keys, verification, backup/PITR/restore

The supported v1 deployment is one organization on one Linux server, with one BoardAgent server, one worker, PostgreSQL 18.6 and Caddy. Runtime containers run read-only as non-root users, with dropped capabilities and separate database principals. Horizontal scale, multi-tenant hosting, public cloud control planes and automatic failover are outside the frozen profile.

Toolchain

• Node.js 24.20.0

• pnpm 11.24.0

• PostgreSQL 18.6

• Docker with Compose v2 for runtime and integration verification

Direct dependencies are pinned exactly. Do not substitute toolchain versions. The recorded provenance is under artifacts/provenance/.

Start here

Evaluate with the Mining Exploration Co pack

The Mining Exploration Co pack is a fictional charter and exercise pack for one non-voting secretary and three equal-weight board members, with a separate setup administrator. Follow its instructions and inspect your own run records before assuming that an instance or an account exists. Creating a fixture, installing a service, issuing an invitation, registering a passkey and completing onboarding are separate steps.

A secretary account does not automatically have a vote, company-administrator powers or a server login. The manuals explain the setup administrator and the supported handoff to the intended board seats. A scripted authenticator or an automated ballot belongs to a test fixture; it cannot establish a real person's acceptance.

Build and check a local checkout

With the exact toolchain versions above, run from the repository root:

corepack pnpm install --frozen-lockfile
corepack pnpm supply-chain:generate
git clone https://github.com/LegalQuants/LQGovernance-OpenBoard vendor/openboard
git -C vendor/openboard checkout 1b38dbf2c1ea413fea0661c34c63cd0fd10dc4bb
corepack pnpm verify:phase0
corepack pnpm exec vitest run tests/unit --no-file-parallelism --maxWorkers=1

supply-chain:generate writes the SBOM and licence report under artifacts/, which are not committed and which the unit suite reads. The vendor/openboard clone is the read-only prior-art reference at its pinned commit; it is git-ignored, never built or imported, and a phase-0 test checks its commit and licence. verify:phase0 checks static integrity and provenance. None of these is a running-system or database qualification. Some browser and released-client prerequisites are separate from dependency installation; tests/TESTING.md explains them. Do not skip a check to make setup pass.

For a disposable local installation, follow DEPLOY.md with reviewed .env.example values and synthetic data. Build the server and PostgreSQL images before starting services. The default server listens on loopback port 8787; it is not a browser governance interface. Use the bootstrap procedure for its one-use operator command.

Keep enrollment links, activation codes, OAuth credentials, secrets and private operator inputs outside source control.

First agent session

After your account is registered and activated, connect your agent to the HTTPS resource ending in /mcp that your operator gives you. A cautious first session is:

1. Connect and log in. Until your onboarding is current the server issues an onboarding:read token and says so in the token response. Call whoami, then list_my_boards.

2. Run onboard-boardagent and inspect get_onboarding, then complete your own attestation. The next token refresh (within fifteen minutes) or a reconnect carries your ordinary scopes.

3. Read get_my_board_snapshot and list_my_updates, then list_pending_actions.

4. Use read tools before any write. For a binding act, inspect the staged exact content and complete the server-driven confirmation yourself.

5. Rehearse an entitled read, then follow the role manual for a synthetic workflow.

The role-by-role guide, the safe prompting rules, the content formats and the confirmation workflow are in docs/AGENT_GUIDE.md. BoardAgent has no shared semantic memory: ADR 0005 explains why canonical shared records stay on the server while any derived memory stays under each person's own agent.

Verification and release labels

The regression net has eleven tiers, T0 to T10. The beta command runs the deterministic tiers T0 to T9; a public release also requires the independent external review at T10.

corepack pnpm verify:private-beta

The command must run against one unchanged source tree, and a passing historical run is not evidence for later edits. docs/VERIFICATION.md maps the 94 original security requirements and the eight approved administrative additions to their implementation and their executing tests; tests/TESTING.md explains how to run the net. A full run writes a release manifest, an evidence ledger, an outcome comparison and a handoff document beside its result receipt. These files collect evidence; they do not approve a release.

Glossary

The documents use a few internal terms. Here is what they mean.

• Gate 1, Gate 2 and Gate 3. The sign-off points of the project. Gate 1 approved the requirements. Gate 2 froze the design: the authority matrix, the data and transaction design, the verification net and the build plan. Gate 3 is production acceptance for one exact build, and it has not been given.

• Frozen. A document or a registry that was fixed at Gate 2 and is pinned by hash. It is not edited; a change is recorded as a separate, additive amendment.

• BUILD_PLAN.md. The build plan as frozen on 28 August 2026. It predates the change to the Apache licence and names a build log and two Gate 2 appendices that are not published in this repository; it is kept unchanged because its hash is pinned.

• Decision records. The files under docs/decisions/ are immutable formal records approved by me, the project owner. Four of them are pinned by hash in the registry amendments and cannot change without regenerating the registry.

• T0 to T10. The verification tiers, in order: integrity, static analysis, unit and state coverage, property tests, mutation testing, PostgreSQL integration, protocol and authentication, adversarial tests, acceptance scenarios, operations, and finally the independent external review at T10, which I cannot issue myself.

• SR-nnn. A numbered security requirement from the verification net. The register in docs/VERIFICATION.md maps each one to code and to a test.

• TH-nn and AC-nn. A numbered threat in docs/THREAT_MODEL.md and a numbered acceptance scenario.

• D2-nnn. A numbered decision from the Gate 2 design record, cited in BUILD_PLAN.md and in the ADRs.

• R, D and H tools. The registry marks every MCP tool as a read (R), a direct non-binding mutation (D) or a binding human act (H). An H tool always runs the prepare, present, confirm and act ceremony.

• S:A and the other scope codes. Short forms of OAuth scopes: S:A is secretariat:admin, G:R is governance:read, V:A is vote:act and M:A is minutes:act. The full list is in the surface matrix under planning/.

• Candidate. One exact source tree, identified by hash, that is being verified for release.

• Receipt. A machine-readable record that a command or a test produced, bound to the exact source it ran against.

• Harvest. The review of an earlier open-source project of mine, LQGovernance-OpenBoard, from which four files were adapted under their original MIT notice. The record is docs/HARVEST_REPORT.md.

• Project owner. Me. Earlier documents used the word sponsor for the same role.

Contributing and reporting problems

Use synthetic reproductions and keep changes scoped to the stated defect. Preserve the immutable migration history, the generated registry contracts and failing evidence. Run the focused checks, then the full net on a clean final tree. The contributor contract, the build plan and the testing guide explain the repository rules.

A useful bug report identifies the exact commit or image, the environment, a non-secret request reference, the expected result, the observed result and minimal synthetic steps. Report vulnerabilities privately through GitHub private vulnerability reporting as described in SECURITY.md. Do not post real board records, invitation URLs, private keys or access tokens in issues.

Documents

• DEPLOY.md: supported topology, secrets, initialization, upgrades and recovery.

• SECURITY.md: threat boundaries, reporting, residual risks and open items.

• docs/AGENT_GUIDE.md: agent onboarding and safe operation.

• docs/SURFACE_REFERENCE.md: generated inventory of the MCP, HTTP, CLI, resource, prompt and event surfaces.

• docs/runbooks/README.md: operator procedures and evidence expectations.

• docs/THREAT_MODEL.md: the threat matrix with controls and proofs.

• docs/KNOWN_LIMITATIONS.md: intentional boundaries, residual risks and open items.

• docs/adr/: accepted architecture decisions.

• CITATION.cff: how to cite this repository.

Licence

BoardAgent is licensed under the Apache License 2.0; see also NOTICE and docs/THIRD_PARTY_NOTICES.md.