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

Authentication note: the connection is scoped to the authenticated user’s visibility — an agent sees exactly what that user can see, no more. Access is never broader than the human whose token it uses.

3. Connect

Everything you need lives in one place in systemHUB: Settings → AI Gateway. It shows four values:

1. Connector URL — your workspace’s MCP endpoint. Copy it exactly; a mistyped URL is the most common cause of connection failures.
2. OAuth Client ID — matches your account subdomain (the part before .systemhub.com).
3. Company alias — your subdomain, lowercase, no spaces (e.g. acme, not Acme).
4. Token — click Generate to create one (or Update to replace it). Treat it like a password; you can revoke it anytime by regenerating.

Then in your AI client — in Claude: Settings → Connectors → Add custom connector — name it systemHUB, paste the Connector URL, OAuth Client ID and token, and add it. Click Connect, enter your company alias when prompted, log in with your systemHUB credentials and approve access. ChatGPT follows the same pattern.

Step-by-step with screenshots: Connecting systemHUB to Claude + ChatGPT (AI Gateway / MCP).

Troubleshooting: an “invalid or expired client ID” error usually means the alias format is wrong (must be lowercase, no spaces) or the token is stale — regenerate it in Settings → AI Gateway. 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

• 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.