This is the MCP / AI reference for systemHUB — written for AI agents and developers. If you are a person looking for how-to help, use help.systemhub.com instead.

Changelog

What changed in the systemHUB MCP and these docs, newest first. The tool reference is regenerated from the stored schema snapshot on every deploy, and states how old that snapshot is; this page records the deltas so a returning agent (or its human) can see what’s new at a glance.

2026-09-07

• Identity binding is fixed, and these docs were still saying it wasn’t. Since 31 Jul every page warned that a session resolved to the workspace’s most-recently-generated token rather than the connecting person. That fix shipped and was verified in production on 27 Aug — so for ten days the docs understated systemHUB’s own security posture to every agent that read them. Corrected on Getting started, Errors & limits, Teach your AI and llms.txt. One gap is still open and now stated plainly: permission enforcement on edits is incomplete — a Reader-level account was observed editing documents it had no edit rights to, while creates and out-of-scope reads were correctly refused.
• The tool reference can no longer promise it is live. The build used to fetch the schema on every deploy, and the page said it therefore could not drift. Closing the identity-binding hole also closed the build’s only unattended route to that schema — /mcp/oauth/authorize now redirects to a consent screen a human must approve, which is correct. The pull failed silently and the reference under-reported the product. Three changes: the build now records that it fell back, the page carries a banner saying how old its snapshot is, and the “generated from the live schema, so it cannot drift” claim is gone from llms.txt and the home page. A snapshot older than 45 days now fails the build outright.
• Known consequence, stated for anyone reading the reference today: tools have shipped that this snapshot predates. Call tools/list on your own connection for the authoritative set.

2026-08-28

• Sharing & links: share links CAN be monitored after all. We said status codes prove nothing, and stopped there — which left anyone distributing share links with no way to detect a dead one. Because the 404 renders client-side, valid and invalid codes both return HTTP 200, but the rendered pages are unmistakable: ~3,500 characters starting with the document title versus ~100 reading “Oh no! Something went wrong.” Render and assert on the title. No auth needed. (This corrects a conclusion the reporter had reached and then disproved himself.)
• Organise the library: tags are case-sensitive. Sales and sales are separate objects with different UUIDs, so filters and counts only match the exact casing — in one audited library that split a single tag 11 documents to 2. add_document_tags matches by exact title and silently mints a new tag for anything that doesn’t, so one capital letter forks your taxonomy. Read existing tag titles and reuse them verbatim.

Four corrections from an independent cold run (Systems Equal Freedom, 28 Aug). Three were our errors, and one had been reported fixed when it wasn’t:

• We told agents "parent": "root" works on get_folder_tree. It does not. The schema describes "root" as accepted while typing the same parameter format: uuid, so it fails validation before reaching the server. Organise the library asserted the opposite — we wrote that confidently on 4 Aug while correcting the create tools, and got the read backwards. Corrected, and the tool reference now carries a correction callout under get_folder_tree printing the upstream description as written and correcting it underneath.
• A broken example survived the fix that was supposed to remove it. The 4 Aug entry below records fixing {"parent": "root"} on the folder-create tools — but only Organise the library was changed. Draft an SOP kept the same broken call for three weeks, in the first guide a new agent reads. Fixed.
• Our workaround for the oversized folder tree didn’t work. Errors & limits said to scope with parent — but "root" is rejected and you have no folder UUID on a first call, so the advice was unusable exactly when it was needed. It now names the route that does work: list_documents_by_owner with type: 1, which returns folders as a flat paginated list with a materializedPath on each.
• …with the catch that route carries. list_documents_by_owner requires an owner, secondary-owner or role filter and gives no indication in the response that filtering occurred. On an account with distributed ownership it returns a partial tree that reads as complete. Documented.

2026-08-27

• Fixed two broken links in the tool reference, found in the edge logs. They were written relative — (concepts/document-lifecycle) — and this page is served at /docs/tool-reference/, so they resolved to /docs/tool-reference/concepts/document-lifecycle and 404’d. Now absolute, and the build fails on any relative link, so it can’t recur. Found by reading actual request logs rather than by review: the broken URL was sitting in the 404s.

2026-08-20

• Fixed a malformed JSON example in the tool reference. The add_document_videos_and_media example lost a closing quote and comma, so an agent copying it would have hit a parse error. Cause was ours: a build-time substitution matched a URL greedily and consumed the delimiter after it. The rule now replaces a whole balanced object rather than editing inside one, and the build now parses every JSON example it publishes and fails if any of them is invalid — regression-tested against the exact broken string.

• llms.txt is now stamped at build time. Its “Last updated” line had read 2026-07-29 for three weeks while the changelog moved on — the exact freshness signal an agent uses to judge whether to trust the file. It now takes the build date automatically, and four canonical facts were synced into it: publish captures the body reliably (the rest unconfirmed), the ~30KB base64 attachment ceiling, the unscoped folder-tree blowout, and that share links are not machine-fetchable.

• The three publish_* tools now carry a correction callout. Their schema descriptions still claim a version snapshot captures content, description, notes, tags, videos, templates and attachments, while an independent restore test reverted only the body. The tool reference prints the upstream description as written and then corrects it underneath — the generated reference is never silently rewritten, so a future schema fix will make the callout visibly redundant instead of invisibly wrong.

• Fixed an example in the tool reference that could not work. The reviewDate example was 2025-06-15 — a past date, which the API rejects, since reviewDate must be today or later. An agent copying it from our own documentation would have burned a call on a guaranteed validation error.

• SEO hygiene: every page now carries a rel=canonical on the www host and its own meta description (all fifteen previously shared one), and the home page no longer renders its title twice as “systemHUB Docs · systemHUB Docs”.

• Added a note at the top of every page stating that this is the MCP/AI reference and pointing humans at help.systemhub.com, so someone who lands here from search knows within a line whether they’re in the right place.

2026-08-19

• Authoring content: made the attachment advice actionable. The page already said “use fileUrl, not base64”, but justified it on cost (“pays for the content twice”), which reads as an optimisation you can skip. It isn’t: above roughly 30KB the base64 path stops working, because the encoded string has to pass through the tool call as one literal and agent harnesses truncate a tool output that large. The page now states the ~30KB ceiling as a hard limit rather than a preference.
• Corrected the Drive example, which would have sent people to the wrong URL. The old text said “a Drive share link” works as a fileUrl. It does not — drive.google.com/file/d/<ID>/view serves an HTML viewer page, and attaching it succeeds while silently storing that HTML instead of the file. There is now a three-step recipe for attaching a local file (upload → link-readable → uc?export=download&id=<ID>), plus the general rule that any host returning raw bytes will do.
• Added the verification step. A wrong URL does not error — add_document_attachments returns success and the attachment contains the interstitial. Nothing in the response reveals this. The page now says to fetch the returned downloadUrl and checksum it against the source before treating the attachment as done.
• Why this changed: an agent attaching a 75KB markdown file to a Business Brain page burned three failed approaches (truncated base64, a blocked static-host deploy, a blocked verification fetch) before landing on the Drive fileUrl route — with the correct answer sitting in these docs the whole time, too softly worded to act on. Guidance that is technically present but not decisive is guidance an agent will walk past.

2026-08-18

• Three corrections from an independent re-test (Systems Equal Freedom, 16 Aug), all cases of these docs being more confident than the evidence supports:

  • Stopped repeating an unverified claim about versions. Document lifecycle and the home page called each publish an “immutable snapshot”, echoing publish_*’s own description. An independent UI restore test reverted only the body content, leaving notes, tags, review date and comments untouched. The discrepancy is open with the product team; until it’s settled the docs describe a version as a reliable record of the body and say plainly that publishing is not a safety net before an agent rewrites metadata.
  • Sharing & links: flagged that a get_ tool can write. get_document_share_link mints a public no-login URL when the document has no code yet. The page mentioned this as a convenience (“generates one if missing”); it now warns that calling it while auditing a library, or while operating deliberately read-only, creates the exposure you were checking for — and points at the shareLink field on reads as the non-mutating alternative.
  • Errors & limits: corrected the folder-tree figure. The page said ~69KB on a 231-document library. On a 396-document library it is ~180KB and exceeds a mainstream AI client’s tool-output limit outright, so the call fails rather than returning something large. With no depth, page or limit parameter there is no supported way to walk the tree in pieces — stated now, because the old figure made it sound survivable.

• NEW guide — Publish your AI’s skills. Teams are writing AI skills (skill files, agent playbooks, custom instruction sets) that never leave the laptop they were written on — the same invisibility problem systemHUB already solves for processes. The guide documents the pattern: an index page grouped by business function and described by outcome rather than mechanics, a page per skill with the file attached via add_document_attachments (a page describing a skill is a brochure; a page carrying the file is installable), and a hard split between business-wired and genuinely shareable skills. Includes the multi-file reality — .zip is rejected and only document types attach, so a skill that’s a folder of scripts needs flattening or linking.

• Fixed a parameter error in Draft an SOP: the versioning example passed publishTitle to publish_system. That parameter belongs to create_system; publish_* takes title, and the schemas are additionalProperties: false, so the example as written would have been rejected.

• Unknown URLs now return a real 404. With no 404.html in the deploy output, Cloudflare Pages had been falling back to the site index and answering 200 for every unmatched path under /docs. Harmless for a human, but this surface is built for agents: an AI that guessed or constructed a URL was told “200 OK, here are the docs” and had no way to learn the page didn’t exist. Unmatched paths now 404 honestly, and the 404 page points at /docs/, llms.txt and the tool reference so a wrong guess still ends somewhere useful.

• Fixed a self-contradiction on Getting started. The “Connecting your team” section still opened with the pre-correction claim that the token is company-level and there is “one token per workspace, not one per person” — then said the opposite two paragraphs later. The stale wording dated from 31 Jul and was superseded that same day by a live test, but was never deleted. Caught by a client asking whether generating their own token would disrupt their admin’s. It would not. The section now states plainly that the server URL and company alias are company-level while the token is per-person, and separates the two questions that were being conflated: who holds a token (per-person, settled) versus which identity a session resolves to (a known open issue, cross-linked rather than restated).

• Also removed the “multi-user connection is being confirmed / field reports conflict” warning from the same section. That was answered on 31 Jul and the field-tested joining procedure directly below it has been the documented answer since.

• Answered the last open question in that section. It said we were “confirming which roles can self-serve” a token. That’s settled: AI Gateway is on admin seats, so a non-admin can’t reach the screen and can’t complete the flow at all. Stated directly now, and cross-linked to Roles & seats, because the consequence matters more than the mechanic — a connected agent has admin-level reach.

2026-08-08

• Tool renamed: generate_document_share_link → get_document_share_link. The rename happened on the live MCP after our last schema pull, so the docs were pointing agents at a tool that no longer exists. Caught in technical review before the public flip. Snapshot re-pulled from the live endpoint and all references updated. (Earlier changelog entries keep the old name — they’re a record of what was true at the time.)
• Reminder for maintainers: the schema snapshot goes stale. Re-pull from the live MCP endpoint as part of any deploy that matters, not just when tools are added.

2026-08-07 (later)

• Tool reference now documents response shapes. Every one of the 48 tools gains a generated Returns table with field names, types and one level of nesting — so state vs documentState and reviewDate vs review_date are answerable from the page instead of by calling each tool and reverse-engineering the response. Generated from the live schemas like the rest of the page, so it can’t drift.
• Corrected the review-debt recipe on Organise the library and Audit access. Both said to find overdue documents by scanning for state: 2 (RED). RED doesn’t set itself, so an untended library reports zero debt. Use reviewDate (on every response) — anything in the past, plus anything with no review date set.
• Sharing & links: noted that opening a share link rewrites to a /guest/ route carrying the alias, and that the section segment isn’t validated — a system’s UUID and code under /policies/ still renders the system, so don’t infer section from the URL.

2026-08-07

Client compatibility documented honestly, after an independent cross-platform test. Getting started previously implied any MCP client would work, with ChatGPT as a “same pattern” aside. That overclaimed:

• Google Gemini CLI is verified working — 48 tools over OAuth against a production workspace, with the exact gemini mcp add command now documented. Retrieval behaviour was identical to Claude’s, confirming the server behaves the same regardless of client.
• Concurrent clients verified — Claude and Gemini CLI held live sessions on the same user simultaneously. One token can serve several clients (generating a new token still disconnects all of your own at once).
• But several clients can’t connect at all: ChatGPT needs a paid tier with developer mode, and the Gemini web app has no custom-server option whatsoever (Gemini Enterprise or the CLI only). A new compatibility table states which clients work, and a rollout warning flags that free-tier users may have no route in.

2026-08-05

From a second-round external audit (Jim Carlin), both on Sharing & links:

• The human-readable share link is not agent-fetchable. It’s a client-rendered view, so a plain HTTP request returns the JavaScript shell rather than the document — and the 404 for a wrong share code is also client-side, so status codes prove nothing. Stated explicitly now, along with the consequence: with the api-host form still 403ing, there is currently no share URL an external agent can fetch without a browser. Share links are for people; programs should use MCP.
• Share codes are not unique per document. Duplicating a document copies its share code, so a copy and its original share one code (reproduced across two document pairs). Index on document UUID, not share code. Two code formats are also in circulation, so don’t validate by shape. Logged with the product team.

2026-08-04

Corrections from a second external field audit (all 15 pages read and cross-checked against the live schemas and a 30-call pipeline run — thank you, Jim Carlin):

• NEW — the human-readable share link is documented. https://{alias}.systemhub.com/systems/{uuid}/{shareCode} renders the published document in a browser with no login (verified 4 Aug in a clean session; a wrong share code 404s). Sharing & links previously said no human app URL existed via the API — that was wrong, and it was steering agents away from a working answer. This is also the practical workaround for the api.systemhub.com 403.
• Fixed a broken example. Organise the library showed {"parent": "root"} on the folder-create tools. parent is typed as a UUID there and "root" is rejected — omit the field for top level. ("root" is valid on get_folder_tree, which is where it was copied from.)
• Corrected the publish model. Document lifecycle implied edits need an explicit publish. They don’t — edit_* auto-publishes, and so do metadata writes: add_document_tags and the template/media/attachment tools default to publish: true. Tagging a document publishes it, which defeats a publish: false created earlier. There is no quiet-editing mode by default.
• Teach your AI no longer writes an ambiguous state fact into permanent agent memory (“drafts are ORANGE” collided with state 0 = GREY/draft and with publish: false); it now names all three senses.
• Corrected the 126KB advice. “Write in sections” made it worse — edit_* replaces the whole content field, so incremental writing resends everything each time. Split across documents instead.
• Also: get_document_activity_log added to the audit tool list, a warning that manage_document_members update replaces roles rather than merging, a pagination warning, and a corrected tool count on Audit access.

2026-07-31 (later)

• Getting started now carries a field-tested team-connection procedure, verified live by a SYSTEMologist agency connecting a second team member: each person generates their own token from their own login, then connects through the existing connector entry and approves as themselves. Added troubleshooting rows for “No active agent token found” and “a server with this URL already exists”.
• Correction: generating a token does not disconnect colleagues. Tokens are per-person — generating revokes only your own previous token and your own sessions. Earlier wording here implied it was account-wide; that was wrong, and it was disproven in a live test (one member generated a token while another stayed connected throughout).

2026-07-31

• Correction — MCP session scoping is workspace-level, not per-user. These docs previously stated that a connection is scoped to the connecting user’s visibility. That is not how the current OAuth flow behaves: a session is bound to the identity on the workspace’s most recently generated AI Gateway token, regardless of who connects. On a multi-user workspace, agents can therefore resolve to the same identity — in either direction (a restricted user inheriting broader visibility, or an admin being scoped down). The claim has been corrected on Getting started, Errors & limits, Teach your AI and llms.txt. A fix binding each connection to the person connecting is logged as a critical item with the product team; these docs will be updated when it ships.
• Practical guidance until then: treat MCP access as workspace-level. Connect agents only for people you’re comfortable seeing everything the token generator can see, and don’t rely on MCP session identity for audit attribution.

2026-07-29

• Docs now live at systemhub.com/docs (review mode — noindex until final technical sign-off). llms.txt and llms-full.txt are served at the systemhub.com root.
• Getting started now carries the confirmed connection details from the product UI: server URL https://mcp.systemhub.com/mcp, OAuth Client ID = company alias, token shown once with a 180-day lifetime (rotation reminder at day 144), and the gotcha that generating a new token immediately revokes the old one and disconnects connected agents (also added to troubleshooting).

2026-07-28

Field-tested by a beta agency (25-call end-to-end SOP pipeline). Two issues confirmed and documented while fixes are tracked with the product team:

• HTML-escaped content is stored silently and publishes as visible tag soup — warning added to Authoring content and the errors table: send raw HTML, read back after writing.
• Share links currently fail external fetch (403 “Company not found”) — Sharing & links updated with the known issue; don’t promise external access until the fix lands.
• Also noted on Sharing & links: no human app URL exists in any API response today (appUrl is a requested enhancement).

2026-07-27

Docs: machine-affordance upgrades (patterns adopted from an audit of Outstand’s docs — the headless reference standard):

• /llms-full.txt — the entire docs corpus in one fetch, generated with every build. Linked from llms.txt.
• Canonical metadata on every raw page — each .md now carries its canonical URL and a connect/auth/tool-count line, so a page quoted into an agent’s context keeps its address.
• llms.txt hardened — dated, with a “Canonical facts” block (authoritative over stale third-party write-ups) and a “What the MCP does not do” list.
• Getting started expanded — per-client connection steps (Claude, ChatGPT, any MCP client) and a six-symptom troubleshooting table.
• Document lifecycle gained a “How systemHUB behaves over time” table — the create/publish/edit/editor-filter sequence an agent should reason with.
• Teach your AI — new page: the first-session prompt and the standing-context briefing an agent saves (CLAUDE.md or equivalent) so every future session can drive systemHUB without re-learning.

2026-07-23

MCP: 5 new tools (snapshot 43 → 48):

• generate_document_share_link — public, no-login share URLs that serve the published document as machine-readable JSON. See the new Sharing & links page.
• get_document_activity_log — per-document audit trail: who created it, who last edited it, full event feed (optionally including view events).
• manage_document_members — write-side document access: assign/remove members and roles on a document.
• list_company_members / list_roles — resolve people and roles by name to UUIDs (companions to manage_document_members).

Known-limits changes these tools unlock:

• “No write-side user management” → narrowed: document-level member/role assignment is now writable. Seat provisioning (inviting people, allocating licences) remains app-UI only.
• “No who-viewed-what telemetry” → narrowed: per-document activity (including views) is now readable via the activity log. Workspace-wide usage analytics remain unavailable.

Docs: added Sharing & links and this changelog; system anatomy in Authoring content extended to Trigger → Steps → Definition of done.

2026-07-22

• Initial public preview: getting started (with real AI Gateway connection steps), quick wins (8 verified prompts), four concept pages, three worked guides, and the full generated tool reference (43 tools).
• Every page dual-served as raw markdown (.md), curated llms.txt published.