Be Civic — Protocol, Trust Model, and MCP Server

Canonical system specifications for the Be Civic project.

Be Civic — Protocol, Trust Model, and MCP Server

This sub-spec covers the trust model and contribution tiers (§7), citation rot mitigation (§11), the provider-integration protocol layer (§21), and the MCP server (§23). These four sections together define who can contribute what, under what rules, through what surfaces.

The submission schemas that back these contribution tiers are in schemas.md. The receiving-end ingestion pipeline that enforces trust rules at the Worker is in privacy.md §8.3. The state machine that advances artefacts after acceptance is in lifecycle.md.

7. Trust model and contribution tiers

In v1, Tier A is consumer-AI submissions of all five feedback types (concern, amendment, validation, draft, feedback) — plus the parallel rating channel added in sprint 2026-W23 (Lock A). Each typed feedback carries an explicit target_type discriminator (except feedback, which has no target). Validation-by-consensus replaces maintainer review for normal corpus growth. The maintainer is constitutional-court only.

Trust signals at the Worker. Per submission, the Worker uses:

• IP address at submission time, stored as salted SHA256 — never plaintext (per G.14, principle 4). Two salts coexist:

  • Daily-rotating salt (sha256(ip + daily_salt); rotates 00:00 UTC) — used for per-IP rate limits (§8.3 (see privacy.md)) and injection-flag DoS defence (§G.6). Short window is the privacy property.
  • Per-artefact salt (sha256(ip + per_artefact_salt); salt generated on first alpha commit / D1 INSERT; persists until the artefact reaches stable or is superseded) — used for self-validation prevention (§G.7) and state-machine distinct-IP counting (§9.2 (see lifecycle.md)). Stable across the artefact's review lifetime so cross-day equality is defined; destroyed with the artefact record on termination. The same scheme applies uniformly to skills, paths, path sources, volatile values, references, and concerns (renamed from observations per the 2026-05-15 taxonomy normalization). The 2026-05-15 amendment reverses S61 (recovery_token dropped pre-launch): session_id remains the recovery key end-to-end; the per-artefact-salt mechanics are unchanged. KV salt-key conventions get a cosmetic rename (proposal:* → submission:*, observation:* → concern:*).

  IP hashes are never persisted to the committed file or to the public corpus.

• submitting_agent string — informational only, used for diagnostics. Spoofable by definition.

• declared_capabilities array — gating per submission type (§6.7 (see schemas.md)). Self-declared; not auditable; advisory at best for trust but used for tier gating.

Committed submissions are anonymous. No per-user identifier, no IP (hashed or otherwise), no GitHub login. Public files cannot be linked back to specific users via repo-readable data.

Maintainer review queue (constitutional-court path). Six classes of submission reach the maintainer:

• Injection-flag quarantines (§G.6) — artefact received ≥1 injection_flag: true validation from a non-submitter
• NER-held submissions (§8.5 (see privacy.md), G.14) — Presidio detected something at commit; submission paused for human eyes
• draft PR review (target_type=skill | path; S31) — every brand-new skill or path PR requires the maintainer to merge. Path amendments (target_type=path | path_source) and skill amendments (target_type=skill) auto-merge on green PR-CI, same as today.
• Operator-private feedback triage (§6.2.5 (see schemas.md)) — the free-text channel lands in an operator-private D1 table (feedback_channel); the maintainer reads it out-of-band. No renderer surface in v1.
• Provider-eligibility decisions (§21) — central editing on objective criteria for partner relationships
• Protocol amendments (Tier B PRs)

Quarantine, NER review, and draft PR review are the maintainer's regular paths in steady state. The maintainer does not review individual concerns, amendments, validations, catalogue corrections, or ratings in the normal flow. The state machine and the validation-by-consensus protocol do that.

11. Citation rot

Citations to government URLs will 404 over time. Defenses:

• Every skill citation may carry an archived_url (Wayback Machine snapshot at time of last verification). Citations should ideally include both, but archived_url is optional.
• Monthly citation-linkcheck.yml Action HEAD-requests every skill citation url. Failures open a Tier B issue listing dead URLs and recommending fallback to archived_url or fresh sourcing.
• For Moniteur belge specifically, prefer permalinks to the official ejustice.just.fgov.be URLs (which exist for legal documents and are stable).
• Consuming agents fetching a citation that 404s should warn the user and check archived_url if available.

Path source rot. The Path Directory introduces a parallel rot surface: path sources carry live deeplinks, portal URLs, and procedure templates that will drift over time independently of skill citations. The lifecycle semantics for path sources — periodic probing, last_validated timestamps, deprecation cascades, and harness-driven validation submission — are specified in §11.1 (see lifecycle.md). Every successful or failed path-source traversal generates a validation submission with target_type=path_source and the traversal_metadata block (per §6.2.3 (see schemas.md); pre-2026-05-15 the same wire shape was named path_validation). CI-probe machine validations carry the same submitter_type: ci_probe marker as today; no structural change to that path. The citation-linkcheck Action does NOT probe audited_document_delivery: true sources; those sources rely on user-driven validation submissions for freshness signals (see §6.12 (see schemas.md)).

21. Provider-integration protocol layer (v1.x ambition)

The protocol layer is Be Civic's commercial sustainability mechanism and the operational realisation of the press-release v4 vision. It is out of scope for v1. It is in scope for v1.x and is described here so the spec describes the target end-state honestly. Operator-facing only — public surfaces avoid this framing at launch (§17 (see architecture.md) commercial-posture entry).

21.1 Shape

When a skill reaches a step that requires a service provider (mortgage broker, notary, shipping company, insurance broker, real-estate agent, etc.), the skill surfaces the eligible providers in the relevant category — and any integrated decision tools that apply (mortgage calculator, comparator, translator). The user's AI sees them, including their published API specifications, and selects one based on the user's situation (income, languages, communes served, fees, preferences). The user's AI then works directly with the chosen provider's API to complete documentation and application forms inside the conversation.

Be Civic is not in the data path for the transaction itself. Documents flow directly between the user (via the user's AI) and the provider. Be Civic's role is the eligibility-vetting layer: it certifies that a provider's API meets the eligibility criteria, lists the provider in the relevant category for AI consumption, and removes the provider for cause when criteria stop holding.

21.2 v1.x scope

v1.x ships:

• A provider directory (separate D1 namespace from the corpus catalogues) listing eligible providers per category, with their published API specs and category-relevance metadata.
• Skill surfacing of eligible providers at transactional moments — the surfacing is editorially neutral (the skill body never names a specific provider; the surfacing is via a dedicated MDX component that resolves the category-keyed provider list at build time).
• Documentation and application-forms completion flows: the user's AI works with the provider API to fill forms inside the conversation, with the user reviewing and approving each step (S45).

v1.x does not ship full transaction completion (signing, payment, regulatory finalisation) inside the conversation. That is longer-horizon ambition; asynchronous provider follow-up over hours-to-weeks via API stretches what current agent infrastructure handles cleanly (S45).

21.3 Editorial-firewall principles (S42)

Eight principles, structurally enforced where the architecture admits enforcement:

1. Skill content is editorially neutral and partner-blind. Skills cite authoritative sources and describe processes; they never name specific providers in the body. Provider surfacing is via a dedicated MDX component that resolves to the directory at build time, not inline prose.
2. Provider integrations expose APIs designed for AI consumption. No promotional sales pitches inside Be Civic. The API specification IS the offering.
3. Be Civic vets integrations for honesty, quality, and non-manipulation. Published rates must match API responses; APIs must not attempt prompt injection on the user's AI; quality and complaint patterns are monitored.
4. Be Civic does not rank or recommend providers. The user's AI selects from the eligible set based on the user's situation. Be Civic publishes the eligibility criteria and the provider's API spec; everything else is the user's-AI's call.
5. Multiple providers per category required. No exclusive integrations. A category with only one eligible provider does not surface the protocol-layer affordance until a second provider qualifies (this prevents accidental monopoly status from gaming the editorial firewall).
6. Pay-for-eligibility, never pay-for-preferential-treatment. Provider revenue funds Be Civic's continued operation; it does not buy ranking, surfacing-order, or category visibility.
7. Removal-for-cause is contractually mandatory and revenue-blind. Manipulation, dishonesty, quality complaints, licence lapse — all trigger removal regardless of revenue impact. The contract IS the firewall.
8. No sponsored skills, ever. Direct payment for content placement is the brightest red line. The skill content is the public corpus; the protocol layer is the commercial layer; they are kept separate.

21.4 Editorial-firewall policy document

The operational policy document (docs/policies/editorial-firewall.md) is drafted before the first partner conversation. Local-only until commerce starts; published on becivic.be/principles alongside the press release at first commerce.

21.5 Maintainer role on provider eligibility

Provider-eligibility decisions are central editing — eligibility involves legal/contract/quality judgment that AIs cannot reliably apply at present. The maintainer (founder) is the editor for partner relationships, applying public criteria. This is a narrow, scoped exception to the "no central editor" posture: skill content stays consensus-driven; provider eligibility is gatekept on objective criteria the maintainer applies. The constitutional-court framing of the maintainer's role (§7) extends to this list naturally.

21.6 Payment model

Not specified at v1 spec time. Likely shape: transaction-percentage commission for most providers, possibly access fees for some categories. Decision deferred to first partner conversation (S44). Press-release v4 uses "Be Civic earns from provider integrations" / "the structure never buys preferential treatment" without specifying access fees vs. commission.

21.7 Out of scope at v1

The protocol layer is out of scope for v1. v1 ships the corpus, the submission protocol, and the state machine. Public surfaces at v1 launch (bc-docs MDX pages) avoid commercial framing; the customer-facing protocol-layer reveal happens later, alongside the editorial-firewall policy document publication.

Path Directory as a provider-facing interface (deferred). v1.x provider integrations MAY include the Path Directory as a published interface to provider partners — for example, a partner who processes dossiers could consume the path catalogue to understand which documents the agent expects, in what format, and through which channels. The specifics (authentication, partner-scoped filtering, dedicated API surface vs. the public endpoint) are out of scope for v1.x planning and will be specified during the first partner conversation (S44). The Path Directory's existence does not block this use; the schema is designed to be consumable by non-agent integrations.

23. MCP server

The MCP server (S54) is a stateless Cloudflare Worker at mcp.becivic.be exposing the public API as ~6 intent-oriented tools to MCP-protocol clients. It replaces the round-6 expectation of a Mintlify-auto-generated /mcp endpoint.

23.1 Architecture

• Stateless Cloudflare Worker at the mcp.becivic.be subdomain, deployed independently of the renderer and the staging Worker.
• Implementation via createMcpHandler (Cloudflare's helper) — sub-100 LOC in practice; no Durable Objects requirement; no session state.
• API-primary: tool implementations are thin wrappers around becivic.be/api/* calls. The public API is the source of truth; MCP is a thin overlay for clients that prefer the protocol over raw HTTP.

23.2 Tool surface (6 write tools post-2026-05-15)

Tool list TBD by the implementation plan; the spec records the principle, not the final names. Direction-of-travel: tools are intent-oriented (e.g. get-graph, read-skill, search-corpus, submit-feedback (envelope), submit-concern, submit-amendment, submit-validation, submit-draft, submit-feedback-channel, submit-rating, get-current-status), each routing to one or more API endpoints. Not 700 thin CRUD wrappers around individual D1 tables; the goal is well-named verbs that match how an AI would describe the intent.

Six write tools (post-2026-05-15 taxonomy normalization). Pre-amendment, the MCP exposed 8 write tools (submit_feedback envelope + submit_observation + submit_validation + submit_amendment + submit_draft + submit_path_amendment + submit_path_draft + submit_path_source_validation). The 2026-05-15 normalization collapses the three path-specific tools into their generalized siblings via target_type=path | path_source. Net result is 6 write tools:

• submit_feedback — polymorphic envelope (recommended primary); items[].type ∈ {concern, amendment, validation, draft, feedback, rating}.
• submit_concern — per-type escape hatch (renamed from submit_observation; hard rename, no alias per locked OPEN-11).
• submit_amendment — per-type escape hatch (now covers skill + path + path_source + volatile_value + reference via target_type).
• submit_validation — per-type escape hatch (now covers skill + volatile_value + reference + path + path_source + observation via target_type; absorbs the prior submit_path_source_validation).
• submit_draft — per-type escape hatch (now covers skill + path via target_type).
• submit_feedback_channel — per-type escape hatch for the new free-text channel (§6.2.5 (see schemas.md)).
• submit_rating — per-type escape hatch for the rating channel (§6.2.7; sprint 2026-W23 Lock A).

(The list above is seven tool names — submit_feedback is the polymorphic envelope; the six per-type escape hatches plus the envelope = 7. The "6 write tools" framing counts the typed write endpoints — the envelope is the primary surface and the per-type tools are escape hatches, conventionally grouped as one polymorphic + six typed = 7 callable names but 6 write-typing concepts. submit_rating was added as the 6th typed concept per Lock A.)

The three path-specific tools (submit_path_amendment, submit_path_draft, submit_path_source_validation) are retired with no deprecated aliases per the operator's pre-launch decision. Path tools have never been publicly marketed; pre-launch removal is clean. (The find_skill-style deprecated-alias precedent does NOT apply here — that was kept for a different reason: legacy CLI / agent muscle memory pre-MCP-tool restructuring on a publicly-marketed skill.)

23.2.0 Skill discovery tools

mcp__becivic__get_graph()

Returns the structured skills graph as JSON — the canonical discovery primitive. The agent fetches the graph once per session, searches within it (by title, summary, applies_to, category) to match the customer's intent, then chains to read_skill with the chosen skill_id to fetch the body.

• Input: no required args. Optional filter args (e.g. category, applies_to) reserved for future use once the corpus outgrows single-response delivery; v1 returns the full rendered subset.
• Output (top-level): { version: <corpus content hash>, generated_at: <ISO8601>, skills: [<entry>] }.
• Output (per-entry): { skill_id, title, summary, status, category, applies_to, requires[], required_by[], requires_paths[], canonical_url }.
  • requires[] — outgoing edges with { id, selects_on? }, mirroring skill frontmatter.
  • required_by[] — reverse index computed at build time (parents that require this skill, with their selects_on predicate where present).
  • requires_paths[] — path-graph dependencies with { id, role, timing }.
  • canonical_url — direct link to the rendered canonical for chaining or citation.

(The round-7.2 routing_risk frontmatter field is retired as of round-7.3 per schemas.md §6.1; risk is now expressed via inline <Risk> tags in the body. get_graph output does not surface it.)

• Scope: rendered skills only (status in alpha | beta | stable). Draft skills are excluded from the public graph; full-universe traversal lives in operations-private artefacts.
• Source: the graph is fetched from https://becivic.be/agents/skills-graph.json, a build artefact emitted by the renderer pipeline alongside manifest.json and errors.json. MCP → HTTPS → WebFetch fallback chain applies.
• Caching: same edge-cache disposition as the other catalogue endpoints; the artefact version field is the content hash, so callers can cheap-check freshness without re-fetching the body.
• Annotations: readOnlyHint: true, idempotentHint: true, openWorldHint: true.

mcp__becivic__find_skill(query) — deprecated alias

Retained for one deprecation cycle (target removal ~2026-08). Internally calls get_graph and applies substring matching against returned titles and summaries, returning the legacy ranked-result shape. Logs a deprecation note to telemetry on each call. Tool description directs callers to use get_graph directly. Scheduled for removal once telemetry confirms no remaining callers.

mcp__becivic__read_skill(skill_id)

Returns the canonical markdown body for a skill. Canonical-only since 2026-05-20 — form rendering moved entirely to the HTTP surface (see "Form fetch" below).

Response shape.

{
  "skill_id": "nationality-application",
  "body": "<markdown body>",
  "canonical_url": "https://becivic.be/skills/nationality-application/canonical",
  "status": 200
}

Caching. Cache-Control: public, max-age=60, s-maxage=60.

Annotations. readOnlyHint: true, idempotentHint: true, openWorldHint: true.

Form rendering is NOT on this tool. The W24 with_form MCP option (D43 single-round-trip optimisation) was dropped 2026-05-20 after dogfood revealed: (a) the combined canonical + form payload (~135K wire) blew the host agent's tool-output budget, forcing fallback to local locale files; (b) the W25.2 handoff-spec-compliance fix moved the procedure walk into a fresh Cowork session, where the cached canonical never carried forward — D43's "single round-trip" benefit was no longer earned. Form fetching now lives exclusively on the HTTP surface at GET https://becivic.be/api/skills/<id>?with_form=1, which returns form_html only (no canonical body). The agent fetches the canonical separately via this MCP tool when the procedure-walking session needs it (per bc-path-traversal Step 2).

Section-1-only form rendering (no candidate procedure matched, "let's figure it out" path) is on a separate MCP tool — see get_onboarding_form below. That tool's payload is small enough (Section 1 fields only, no procedure Section 2 + no canonical) to stay on the MCP surface without the same tool-output-budget issue.

Sentinel payloads for deferred-capture form inputs (W25, 2026-05-19). Some form-input types support capture modes that defer the actual value capture to post-submit chat or filesystem-watching workflows. When such a mode is selected, the submitted form value carries a sentinel object instead of the final value:

{
  "<field_name>": { "__mode": "<capture_mode_id>", "__status": "pending" }
}

Receiving harnesses (e.g. bc-onboarding under the Cowork plugin) detect the __status: "pending" marker, run the mode-appropriate post-submit hydration (chat elicitation, folder polling + vision extraction, etc.), present the resulting structured value back to the user for confirmation (typically by re-rendering the same widget pre-populated), and write the final value to its target store (case.json or profile.json per the input's render: directive). Sentinel-shape schema validators MUST reject {__mode, __status} payloads on input types that don't declare capture modes. Currently the only input type that supports deferred-capture sentinels is row_list (see schemas.md "Form-input types"). Other input types may declare capture modes in the future via PR to schemas/types.json.

mcp__becivic__get_onboarding_form(skill_id?, app?, locale?, mode?, pre_selected?, profile_snapshot?)

Returns a branded onboarding form HTML, ready for the agent to show via mcp__visualize__show_widget (or any compatible widget surface). Two shapes determined by whether skill_id is set:

• No skill_id — Section 1 only (no procedure block, no consent). Use at first contact when the agent doesn't yet know which procedure the user wants. The "low-confidence intent — let's figure it out" path (D34 first-contact mode with no matched skill).
• With skill_id — server fetches the named skill's canonical, extracts its inputs: block, renders Section 1 + Section 2 + consent (for first-contact mode) or just Section 2 (returning / multi-active modes).

The response is form HTML only — never includes the canonical body. To fetch the canonical, call read_skill separately (procedure-walking sessions do this via bc-path-traversal Step 2). This split was introduced 2026-05-20 after the W24 combined-shape (D43) blew the host agent's tool-output budget; see the read_skill section above for the full rationale.

Response shape.

{
  "form_html": "<branded HTML>",
  "locale_actual": "en",
  "locale_fallback_reason": null,
  "version": "<corpus content hash>",
  "skill_id": "<echoed when skill_id was set>"
}

Caching. Cache-Control: private, no-store (per-call rendering varies with pre_selected).

Annotations. readOnlyHint: true, idempotentHint: false, openWorldHint: true.

HTTP parity. Both MCP tools have HTTP-parity endpoints under becivic.be/api/:

• GET /api/skills/<skill_id> — canonical body (mirrors read_skill).
• GET /api/onboarding-form — Section-1-only form (mirrors get_onboarding_form without skill_id).
• GET /api/onboarding-form?skill_id=<id>&app=cowork&locale=en&mode=first-contact — full procedure form (mirrors get_onboarding_form with skill_id).
• POST /api/onboarding-form — body carries the full request shape; pre_selected and profile_snapshot go in the POST body (too large for query strings).

23.2.1 Path Directory tools

The following tools extend the tool surface to cover the Path Directory (§6.12 (see schemas.md)). Each tool is a thin wrapper around its HTTP parity endpoint, listed alongside.

mcp__becivic__get_path_directory(filters?)

Returns the full path catalogue, optionally filtered. HTTP parity: GET /api/paths.

• Input: optional filters object with fields themes (string array), purpose (string), applies_to (object), status (string).
• Output: { generated_at, filters_applied, paths: [<path entry>], total: N }.
• Caching: Cache-Control: public, max-age=60, s-maxage=60 (edge-cached; short TTL because path entry status changes as the validation cohort progresses).
• Quarantined filtering. The default list omits entries with status: quarantined, matching the renderer rule (§20.11 in website.md). Callers can still surface quarantined entries with an explicit status: 'quarantined' filter (operator / audit use). The single-entry get_path / GET /api/paths/<path_id> route returns entries regardless of status so direct lookups distinguish 404 (absent from catalogue) from a 200 carrying status: quarantined (audit record retained).

Intended use: the harness fetches the catalogue once per session (or uses a cached copy) and traverses in-memory to resolve which paths apply to the current user context.

mcp__becivic__get_path(path_id)

Returns a single path entry by ID. HTTP parity: GET /api/paths/<path_id>.

• Input: path_id string (kebab-case path identifier, e.g. marriage-certificate-belgian).
• Output: one path entry in the same shape as get_path_directory.paths[*].
• Caching: same Cache-Control as get_path_directory.

Intended use: when the harness has resolved a path ID from the directory index but wants a fresh single-entry fetch (e.g. after a validation round has updated the path entry's status).

Path validation, amendment, and draft via the generalised tools (2026-05-15 normalization). The three pre-amendment path-specific MCP tools (submit_path_source_validation, submit_path_amendment, submit_path_draft) are retired with no deprecated aliases. Agents file path-targeted submissions via the generalised tools, which dispatch on target_type:

• A per-source validation after a traversal attempt → submit_validation({ target_type: 'path_source', target_id: '<path_id>:<source_id>', verdict, rationale, traversal_metadata }). HTTP parity: POST /api/validations (single route, polymorphic over all six target_type values). The traversal_metadata block — structured signals from the traversal attempt mirroring validation_path.success_signals / failure_signals from §6.12 (see schemas.md) — is preserved verbatim.
• An amendment to an existing path or path source → submit_amendment({ target_type: 'path' | 'path_source', target_id, content: { amendment_subtype, frontmatter_change | source_add } }). HTTP parity: POST /api/amendments. Auto-merges on green PR-CI (same as skill amendments).
• A new path entry → submit_draft({ target_type: 'path', proposed_id, content: { entry } }). HTTP parity: POST /api/drafts. Maintainer review required, same as target_type=skill drafts (S31).

Trust rules unchanged: Worker-side scrub, rate-limit, self-validation prevention, and per-artefact salt all apply identically to skill-targeted and path-targeted submissions (the per-artefact salt for target_type=path_source is path-scoped, not source-scoped, per §6.2.3 (see schemas.md)).

23.3 "API is the new old MCP"

The architectural premise: a well-designed REST API with discoverable resources is sufficient for most agents (they speak HTTP fluently and AI-native API design is well-trodden); MCP exists as a convenience for protocol-native clients, not a primary surface. Building MCP first leads to bespoke MCP-only logic; building API first lets MCP be a thin overlay.

23.4 Out of scope at v1

• MCP-specific authentication (v1 MCP is read-only or unauthenticated; submission tools may proxy through API submission flow with the same rate limits).
• MCP-specific extensions beyond the API surface (any new capability is API-first).
• Per-vendor MCP variants — the Worker exposes the standard MCP protocol; vendor-specific shims live in the consumer.

Cross-references

Cross-doc references are inlined throughout this document in the form §X.Y (see .md). The list below was the pre-reconciliation manifest from the 2026-05-11 split, retained for audit; it can be deleted at the next split-or-merge cycle.

• §6.2.2 (Submission schemas / skill_amendment shape) — see schemas.md §6.2.2
• §6.2.3 (Submission schemas / skill_draft shape) — see schemas.md §6.2.3
• §6.2.4 (Submission schemas / validation shape and target_type keying) — see schemas.md §6.2.4
• §6.7 (Agent capability requirements / declared_capabilities) — see schemas.md §6.7
• §6.12 (Path Directory schema — path entries, source entries, source classes, actor block) — see schemas.md §6.12
• §8.3 (Receiving-end ingestion pipeline / rate limits / self-validation prevention) — see privacy.md §8.3
• §8.5 (NER-held review queue) — see privacy.md §8.5
• §9.2 (State-machine distinct-IP counting) — see lifecycle.md §9.2
• §11.1 (Path source rot — periodic probing, last_validated, deprecation cascade) — see lifecycle.md §11.1
• §17 (Settled decisions / commercial posture) — see architecture.md §17
• §20 (Website rendering / renderer Worker routing) — see website.md §20