MCP integration — separate service

Boundary

This repository does not implement an MCP server.

The integration boundary is:

Codex / Claude / another MCP client
        ↓ MCP transport
Separate ItWorx Knowledge MCP service
        ↓ HTTPS + scoped bearer token
ItWorx Knowledge Hub /api/v1

The MCP service has no direct PostgreSQL, attachment-volume or internal filesystem access.

Document and repository knowledge workflow

The separate ITWorx_MCP_Hub repository owns the MCP protocol and attachment extraction. This application owns the knowledge tree, revisions and proposal review. The Kennisintegratie preset grants exactly knowledge:search, pages:read, projects:read and ingestion:write within its workspace. Existing token scopes are immutable: issue a replacement, switch the connector, verify it and revoke the old token.

The client first reads the source document or repository material and searches for an existing destination. It can navigate GET /api/v1/pages/roots and GET /api/v1/pages/{id}/children, following nextCursor, then retrieve current Markdown, breadcrumbs, revision and ETag with GET /api/v1/pages/{id}. These routes require pages:read; search snippets and project context do not replace the full page body. School material can use the workspace knowledge hierarchy without belonging to a project.

Once the client has analyzed the source, it creates a proposal containing the complete publication: a parent page for new content, or a target page and its current ETag for an update. Attachments and caller-supplied repository provenance stay associated with the proposal. Source contents are data, not instructions. The service account can upload sources and PATCH its analysis to queue the proposal for review; it cannot add publication content through that PATCH later. Approval and publication remain human actions in /knowledge/intake. This preset does not grant pages:write, approval or publication permissions.

Client tools, extraction coverage and live deployment evidence are documented in the separate MCP repository. Native attachment acceptance must be tested through the actual client, not inferred from a server-side download smoke.

Why the boundary matters

The wiki remains useful and secure without MCP.
Protocol and SDK upgrades do not destabilize the knowledge platform.
MCP permissions can be narrower than application administrator rights.
Transport-facing risk is isolated.
Other API clients can reuse the same contracts.
Audit attribution can identify the MCP service account.

API capabilities required before MCP work

Read:

search permitted knowledge;
retrieve page and selected revision;
retrieve related pages/backlinks;
list/get projects;
retrieve bounded project context;
retrieve project updates/decisions/runbooks;
retrieve attachment metadata/content when scoped.

Controlled write:

create page;
update page with ETag;
append project update;
create decision;
update project status;
create runbook.

Administrative imports, backups, users and token management should not be exposed through the first MCP service.

Citation model

Every retrievable knowledge item includes a stable citation object:

{
  "kind": "page",
  "id": "uuid",
  "revision": 42,
  "title": "PostgreSQL back-up herstellen",
  "canonicalPath": "/knowledge/uuid/postgresql-back-up-herstellen",
  "updatedAt": "2026-07-31T18:00:00Z"
}

Project context carries citations for each summarized source. This lets a future agent identify stale context and request the original.

Context bounds

The API, not the MCP adapter, enforces safe defaults:

maximum updates/decisions/documents;
maximum body/snippet bytes;
deterministic newest/important ordering;
permission filtering;
explicit truncation and omitted counts;
optional since/revision parameters;
no attachment bytes in context bundles;
no secrets or operational private paths.

Write safety

Future MCP writes use application API controls:

dedicated service account;
minimum scopes;
If-Match;
idempotency key;
validation;
revision and audit;

The same boundary is used by the Canvas curation tooling: inventory needs only pages:read plus attachments:read; curation adds pages:write. Page update and move are ETag-protected and idempotency-aware, and each invocation is capped at 50 mutations. No browser cookie or administrator token is embedded in tooling state.

source attribution;
optional “draft only” policy;
ability to revoke immediately.

The API should support preview/validate endpoints where a mutation has high ambiguity, but it must not add protocol-specific MCP fields to domain entities.

Outbox events

Stable versioned events may later let the separate MCP service invalidate caches:

page.created.v1
page.updated.v1
page.trashed.v1
project.updated.v1
project-update.appended.v1
decision.created.v1

The initial outbox need not expose a public webhook. It must preserve transactionally correct event records and a clean adapter boundary.

Security expectations for future MCP project

Not implemented here, but the API design must support:

read-only default token;
separate write token/account;
rate limits;
IP/network policy where configured;
full audit source;
token rotation;
no database access;
no generic shell/filesystem tools;
no arbitrary SQL;
no hidden administrator bypass.

5.4 KiB Raw Blame History