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.

Getting started

This guide gets an AI agent or technical user connected to systemHUB through the MCP server and making a first read call.

1. What the MCP server is

The systemHUB MCP server exposes your company’s systemHUB content — Systems, Policies, and Trainings — to an AI agent as a set of callable tools. An agent that speaks the Model Context Protocol can connect to it, discover the available tools, and call them to search, read, author, and audit content on your behalf.

2. Prerequisites

A systemHUB account with content you want the agent to reach.
AI Gateway access enabled on your plan (included with Accelerator). If you don’t see AI Gateway under Settings, contact support@systemology.com.
An MCP-capable client (e.g. Claude, ChatGPT, or any agent framework that supports MCP servers).

✅ Identity binding is fixed (verified in production, 27 Aug 2026). A connection now resolves to the person who logged in and approved it, not to whoever generated the workspace’s most recent token. Each person needs their own AI Gateway token; sessions no longer inherit someone else’s identity.

⚠️ One gap is still open. Permission enforcement on edits is not yet complete — in systemHUB’s own testing a Reader-level account was able to edit existing documents it had no edit rights to. Creates and out-of-scope reads were correctly refused. So treat identity as trustworthy and edit permissions as not yet fully enforced when planning who connects.

3. Connect

Everything you need lives in one place in systemHUB: Settings → AI Gateway. Three things matter:

Server URL — https://mcp.systemhub.com/mcp (the same for every workspace).
OAuth Client ID — your company alias, which is your account subdomain (the part before .systemhub.com), lowercase, no spaces (e.g. acme, not Acme).
Token — click Generate New Token and copy it immediately; it is shown only once. Tokens live for 180 days from generation (you’ll get an email reminder at day 144 to rotate). ⚠️ Generating a new token immediately revokes the existing one and disconnects any AI agent currently connected with it — they’ll need to reconnect with the new token.

Then connect from your AI client:

Claude (web or desktop): Settings → Connectors → Add custom connector — name it systemHUB, enter the server URL https://mcp.systemhub.com/mcp, and in advanced settings set the OAuth Client ID to your company alias and paste the token. Click Connect, log in with your systemHUB credentials and approve access.
Google Gemini CLI (verified 7 Aug 2026): gemini mcp add -s user --transport http systemhub https://mcp.systemhub.com/mcp, then /mcp auth systemhub and complete the browser flow. /mcp should then report systemhub - Ready (48 tools) (OAuth).
ChatGPT (paid tiers): Settings → Advanced Settings → Create App. Name it systemHUB, paste the Connector URL, and set the OAuth Client ID to your company alias with the token you generated. Then complete the Connect/approval step — adding the app and authorising it are two separate actions, and stopping after the first leaves a connector that appears in the list but exposes no tools.
Any other MCP client (agent frameworks, IDEs): configure a remote MCP server with the Connector URL as the endpoint and OAuth as the auth method, then complete the browser login when prompted. The MCP Inspector is a quick way to verify the server responds before wiring it into an agent.

Which AI clients can actually connect

The MCP protocol is open, but not every client lets you add a custom server, and several gate it behind a paid or admin tier. Verified 7 Aug 2026:

Client	Custom MCP server?	Notes
Claude (web, desktop, Code)	✅ Yes	Paid plan. Verified.
Google Gemini CLI	✅ Yes	Free, but technical (Node install). Verified end to end against a production workspace. Needs an AI Studio API key for the CLI’s own model auth — on a Workspace account that also means importing a Cloud project.
ChatGPT	✅ Yes, paid tiers	Settings → Advanced Settings → Create App (not “developer mode” — that term sends people looking for a setting that isn’t the one). Paid plan required; not available on the free tier. On Business/Enterprise workspaces, adding an app may be restricted to a workspace admin.
Gemini web app	❌ No	Connected Apps is a curated catalogue with no way to add a custom server. Custom MCP needs Gemini Enterprise (admin-registered) or the CLI above.

Plan for this when rolling out to a team. Someone using free ChatGPT or the Gemini web app cannot connect at all — no setting exists. They’ll need a paid AI client, or the Gemini CLI if they’re comfortable in a terminal.

One token, several clients. You can connect more than one AI client with the same token — Claude and Gemini CLI running against the same workspace concurrently has been verified, as has Claude desktop plus Claude web. Remember that generating a new token disconnects all of your own connected clients at once (see above).

Step-by-step with screenshots — two separate articles: Connecting systemHUB to Claude · Connecting systemHUB to ChatGPT.

Connecting your team

The server URL and company alias are company-level — everyone in the workspace uses the same two values. The token is not. Each person generates and holds their own.

Two things that used to differ, and now agree. Tokens are per-person: generating yours revokes only your own previous token and disconnects only your own agents — a colleague’s connection is untouched (verified 31 Jul 2026). Which identity a session resolves to is now also per-person, as of the 27 Aug fix. So “my token is mine” and “my agent sees what I see” are both true today — with the one caveat that edit permissions are not yet fully enforced, see Prerequisites.

Each person generates their own token — don’t pass yours around. Sharing a token means your colleague’s agent runs with your identity and access. Generating your own token does not disconnect your colleagues: tokens are per-person, and generating one only revokes your own previous token and your own sessions.

Adding a team member (field-tested procedure):

They log into systemHUB as themselves → Settings → Company → AI Gateway → Generate New Token. This is their token, separate from everyone else’s.
In their AI client, use the existing systemHUB connector entry and click Connect — in a shared Claude Teams workspace, one person adds the connector once and everyone else connects through it.
They enter the company alias, sign in as themselves, and approve. Done.

Don’t add a second custom connector pointing at the same server URL — the client rejects it with “a server with this URL already exists”. If a connector for systemHUB is already in the workspace, connect to that one.

⚠️ If they haven’t generated their own token first, the approve step fails with “No active agent token found”. That’s the most common cause of a failed team connection — generate the token, then approve.

Also worth knowing:

AI Gateway is on admin seats today, so Settings → Company → AI Gateway is only reachable by admins. A team member without an admin seat can’t generate a token and so can’t complete this flow at all. That’s the current access model rather than a permissions quirk — read Roles & seats before planning a wider rollout, because it means a connected agent has admin-level reach.
MCP activity is attributable again. Since the 27 Aug identity fix, the activity log names the person who approved the connection, so agent actions attribute correctly. (Before that, sessions could report as the newest token’s identity.)

Troubleshooting

Symptom	Likely cause → fix
”Invalid or expired client ID”	Company alias format is wrong (must be lowercase, no spaces) or the token is stale → regenerate in Settings → AI Gateway.
Tools don’t appear in the client	Connection added but not authorised → re-run Connect and complete the login/approval; after regenerating a token, reconnect.
Agent was working, suddenly can’t connect	You generated a new token (which revokes your own previous one), or your token passed its 180-day lifetime → reconnect. A colleague generating their token does not affect you.
”No active agent token found” on the Approve Connection screen	You reached the consent screen signed in as yourself, but you don’t have a token of your own — someone else’s token doesn’t satisfy this check → generate your own in Settings → AI Gateway, then approve again. This is the per-user path working as intended.
”A server with this URL already exists”	You’re adding a new custom connector for a systemHUB server already configured in that workspace → don’t add a second one; connect through the existing entry.
”Document not found” on a document that exists	Visibility scoping — the connected user can’t see it — or it’s a master template (`get_*_details` returns 404 on those by design).
400 on an owner lookup	Full name didn’t match exactly → use the exact name from a tree node, or the user UUID.
502 on a large edit	Content over ~126KB → split the document or write in sections.
”My formatting changed after a human edited the doc”	You authored outside the supported set; the editor filtered it → see Authoring content.

More failure modes: Errors & limits.

4. Your first call

Once connected, the agent should orient before acting:

Map the structure — call get_folder_tree (Systems), get_policy_tree (Policies), or get_training_tree (Trainings) to see folders and documents, their owners, and publication state.
Find a document — call search_by_name (systems), search_policy, or search_training with a title fragment.
Read it — call get_system_details / get_policy_details / get_training_details with the document UUID to pull full content, overview, tags, media, and comments.

A minimal “can you see my systems?” smoke test is a single get_folder_tree call with no arguments — it returns the top of the Systems tree.

5. Good-citizen rules for connecting agents

Read before you write. Orient with the tree/search tools before creating or editing anything.
Respect master templates. Nodes flagged isMasterTemplate: true are read-only reference content from the master workspace — never edit, move, publish, or delete them. get_*_details returns 404 on them by design.
Match names exactly for owner lookups. list_documents_by_owner needs the person’s full name exactly or their user UUID.
Publishing is deliberate. Creating a document with content publishes it automatically so assigned users can see it. Pass publish: false to keep a draft. See Document lifecycle.
Author within the supported formatting set. The editor silently strips unsupported HTML on the next human save. See Authoring content.

Next: Quick wins → — verified copy-paste prompts for your first ten minutes connected — or dive into Document lifecycle.