# Getting started (https://systemhub.com/docs/getting-started)

> Part of systemHUB Docs · Connect: Settings → AI Gateway in systemHUB · Auth: OAuth (scoping is workspace-level today — see Getting started) · MCP tools: 55 · Full corpus: https://systemhub.com/llms-full.txt

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](https://modelcontextprotocol.io) 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](mailto: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:

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 your existing one** and disconnects any AI you connected with it — reconnect with the new token. Tokens are per person, so this never affects anyone else's connection.

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): turn on **Developer Mode** first — ChatGPT requires it for any connector that can create or edit. Then create the app: on **Business** it's Workspace Settings → Apps → Create (admin only); on **Enterprise/EDU** it's Settings → Apps → Advanced Settings → Create (admin only). Name it `systemHUB`, paste the Connector URL, choose **OAuth**, put your company alias in **OAuth Client ID** and your token in **OAuth Client Secret**. 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 | Needs **Developer Mode** on — ChatGPT's own requirement for connectors that can write; there is no workaround. Paid plan required; **not available on the free tier**. On **Business/Enterprise/EDU**, creating the app is admin-only; each person still connects and approves as themselves. |
| **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**](https://kb.systemology.com/help-center/connecting-systemhub-to-claude-ai-gateway-/-mcp) · [Connecting systemHUB to **ChatGPT**](https://kb.systemology.com/help-center/connecting-systemhub-to-chatgpt-ai-gateway-/-mcp-0).

### 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](#2-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):**

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:

- **AI Gateway is on for admins. For other roles, systemHUB support switches it on.** If a team member can't see Settings → AI Gateway, their role doesn't have MCP access yet. A customer admin can't enable it from their own Permissions screen, so email **support@systemology.com** and say which roles (Editor, Contributor, Reader). Each person's AI then gets exactly their own seat's permissions: a Reader's AI can read but not change anything. See [Which roles can connect an AI](/docs/concepts/roles-and-seats#which-roles-can-connect-an-ai).
- **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](/docs/concepts/authoring-content). |

More failure modes: [Errors & limits](/docs/concepts/errors-and-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) with no arguments. Since 22 Sep 2026 that returns the **top level only** (`depth` defaults to 1, `limit` to 50) plus `total` and `hasMore`. Open a folder by calling again with its id and `depth: 1`, rather than pulling the whole library at once.
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.

> ⚠️ **If your agent was connected before 22 Sep 2026, re-read its standing instructions.** A bare tree call used to return the entire library, so an agent told to "read the structure once" will now silently see only the top level. That is the fix working, not a fault — but the instruction needs updating to drill in with `parent` + `depth`.

## 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](/docs/concepts/document-lifecycle).
- **Author within the supported formatting set.** The editor silently strips unsupported HTML on the next human save. See [Authoring content](/docs/concepts/authoring-content).

Next: **[Quick wins →](/docs/quick-wins)** — verified copy-paste prompts for your first ten minutes connected — or dive into **[Document lifecycle](/docs/concepts/document-lifecycle)**.