# 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](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).

> 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)](https://kb.systemology.com/help-center/connecting-systemhub-to-claude-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](/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) 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](/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)**.