View as markdown

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

⚠️ Authentication note (important, being fixed): a connection is currently scoped to the identity attached to the workspace’s most recently generated AI Gateway token — not to each person who connects. On a workspace where several people connect, everyone’s agent can therefore resolve to the same identity and visibility. Treat MCP access as workspace-level for now: only connect agents for people you’re comfortable seeing everything the token generator can see. A fix binding each connection to the person connecting is in progress — see the changelog.

3. Connect

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

  1. Server URL — https://mcp.systemhub.com/mcp (the same for every workspace).
  2. OAuth Client ID — your company alias, which is your account subdomain (the part before .systemhub.com), lowercase, no spaces (e.g. acme, not Acme).
  3. 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:

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:

ClientCustom MCP server?Notes
Claude (web, desktop, Code)✅ YesPaid plan. Verified.
Google Gemini CLI✅ YesFree, 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⚠️ Paid tiers onlyReported to require Plus or above with developer mode. Not available on the free tier.
Gemini web app❌ NoConnected 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: Connecting systemHUB to Claude + ChatGPT (AI Gateway / MCP).

Connecting your team

The server URL, alias, and token are company-level — there is one token per workspace, not one per person.

⚠️ Multi-user connection is being confirmed (as of 31 Jul 2026). Field reports conflict: some workspaces have connected several team members with the same values, while in others additional members hit an error even when they are systemHUB admins. We are also confirming whether the connection carries the token generator’s access or each member’s own access — until that’s answered, don’t assume an editor’s AI is limited to editor permissions. If you’re rolling out to a team, connect one person first and check with support before wider rollout. This note will be updated when the behaviour is confirmed — see the changelog.

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):

  1. They log into systemHUB as themselves → Settings → Company → AI Gateway → Generate New Token. This is their token, separate from everyone else’s.
  2. 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.
  3. 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:

Troubleshooting

SymptomLikely 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 clientConnection added but not authorised → re-run Connect and complete the login/approval; after regenerating a token, reconnect.
Agent was working, suddenly can’t connectYou 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 screenYou 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 existsVisibility 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 lookupFull name didn’t match exactly → use the exact name from a tree node, or the user UUID.
502 on a large editContent 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:

  1. 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.
  2. Find a document — call search_by_name (systems), search_policy, or search_training with a title fragment.
  3. 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

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