Connecting systemHUB to Microsoft Copilot Studio (AI Gateway / MCP)

🔑 Before You Begin

• You need AI Gateway access. If you don't see Settings → AI Gateway, email support@systemology.com and we'll switch it on for your role (admin seats have it by default).
• You need access to Microsoft Copilot Studio with permission to create or edit an agent. The standard Microsoft 365 Copilot Chat can't add custom connections, so this needs Copilot Studio.
• Anyone who will use the agent needs a Microsoft 365 Copilot licence. On the standard engine (Step 2), that's all they need, with no extra cost.
• You'll need your Microsoft 365 admin to approve the agent at the end (Step 7), so it's worth giving them a heads-up.
• Have your systemHUB login handy, you will approve the connection at the end.
• Treat the token you generate like a password. Do not share it.
• Use Claude? Click here for Claude connection instructions.
• Use ChatGPT? Click here for ChatGPT connection instructions.

🧭 Step 1 — Get your connection details from systemHUB

1. Log in to systemHUB.
2. Go to Settings → AI Gateway.
3. Copy the Connector URL exactly as shown (a wrong character here is the #1 cause of failures).
4. Note your company alias, this is your account subdomain (the part before .systemhub.com). Example: if you log in at acme.systemhub.com, your alias is acme.
5. Click Generate to create your token. Each person needs their own token before they can approve a connection. ⚠️ If you already have one, only click Update if you need to. It revokes your old token and disconnects any AI you connected with it, including Claude or ChatGPT.

🤖 Step 2 — Create your agent on the standard engine

When you create a new agent, Copilot Studio asks which engine to use: standard or GitHub Copilot. Both can connect to systemHUB, but we strongly recommend standard.

• Standard: you can build, test and deploy the agent, and anyone with a Microsoft 365 Copilot licence can use it at no extra cost.
• GitHub Copilot: building, testing and every person's use of the agent runs on Copilot Credits. A Microsoft 365 Copilot licence doesn't cover this, and if your organisation has no credits you'll just see "You need credits to continue".

1. Open Copilot Studio and create a new agent.
2. When asked to choose an engine, select standard.
3. Give your agent a name and finish creating it.

Already have an agent you'd like to use? Check which engine it's on first. If it's on GitHub Copilot, everyone using it will need Copilot Credits.

🔌 Step 3 — Add systemHUB as a tool in Copilot Studio

1. Open the agent you created in Step 2.
2. Go to the Tools page for your agent.
3. Click Add a tool → New tool → Model Context Protocol. The MCP setup window will appear.
   • On the GitHub Copilot engine, this menu doesn't exist. Go to Build → Tools → Add → Model Context Protocol (MCP) instead.
4. Enter your systemHUB details from Step 1:
   • Server name: systemHUB
   • Server description: Reads and manages our company's systems, policies and training content in systemHUB. (Copilot uses this description to decide when to use systemHUB, so keep it clear.)
   • Server URL: paste the Connector URL from Step 1 (double-check it is exact).
5. Under Authentication, select OAuth 2.0, then select Dynamic discovery as the type.
6. Click Create, then click Next.

✅ Step 4 — Connect and approve

1. In the Add tool window, select Create a new connection.
2. A new window will now appear for you to sign into systemHUB.
3. When prompted, enter your company alias, this is your subdomain, all lowercase with no spaces (e.g. acme, not "Acme" or "My Company"), then click Continue.
4. Log in with your systemHUB credentials and click Approve Connection.
5. Back in Copilot Studio, click Add to agent. systemHUB will now appear in your agent's Tools list.

🧪 Step 5 — Test the connection

1. Open the Test panel for your agent in Copilot Studio.
2. Then ask: "Can you check the folder tree and tell me what main root-level folders I have in my systemHUB account?"
3. If Copilot asks you to sign in or allow access, approve it. Copilot will then return your folders, which confirms it is working!

At this point the agent only exists in the Test panel. The next two steps make it available to your team.

🚀 Step 6 — Publish your agent to Teams and Microsoft 365 Copilot

Until you publish it, your agent only exists in the Test panel and nobody else can use it.

1. In Copilot Studio, click Publish on your agent and confirm.
2. Go to Channels and select Teams and Microsoft 365 Copilot.
3. Turn the channel on. When asked who can use the agent, choose Show to everyone in my org. This sends it to your Microsoft 365 admin for approval (Step 7). If you only share it with specific teammates, nothing reaches your admin to approve.

Once it's published, your Microsoft 365 admin needs to approve it before your team can see it (Step 7).

🛡️ Step 7 — Ask your Microsoft 365 admin to approve the agent

This step is for your Microsoft 365 admin. Without it, the agent is live but nobody in the business can see it.

1. Open the Microsoft 365 admin centre.
2. Go to Copilot → Agents.
3. Find the systemHUB agent, approve it, and choose who in the business can use it.

Once it's approved, your team will find the agent in Teams and Microsoft 365 Copilot. Each person approves their own systemHUB connection the first time they use it, so make sure everyone has generated their own token (Step 1).

🛠️ Troubleshooting

• "You need credits to continue"
  • Your agent is on the GitHub Copilot engine, which runs on Copilot Credits. Create a new agent on the standard engine (Step 2) and add systemHUB to that one instead.
• "Invalid or expired client ID"
  • This is almost always the company alias or the token.
  • Check the alias is your exact subdomain, lowercase, no spaces (acme, not "Acme" or your company name).
  • Your token may have expired or been regenerated, so go back to Settings → AI Gateway, generate a fresh token, and reconnect.
  • Confirm the Connector URL was pasted exactly.
• No "AI Gateway" option under Settings
  • Your role doesn't have AI access switched on yet. Only systemHUB support can enable it for Editor, Contributor and Reader roles, so email support@systemology.com and tell us which roles. Once it's on, each person's AI gets exactly their own seat's permissions: a Reader's AI can read but can't change anything.
• "No active agent token found" when approving
  • You haven't generated your own token yet. Each person needs their own. Generate one in Settings → AI Gateway, then approve again.
• Dynamic discovery fails or won't create the tool
  • Go back to Authentication and select Manual instead, then enter:
  • Client ID: your company alias
  • Client secret: your token
  • Authorization URL: https://master.systemhub.com/mcp/register
  • Token URL: https://mcp.systemhub.com/oauth/token
  • Scope: leave blank
  • ⚠️ Heads-up: with Manual, the connection runs on the token of whoever built the agent, so everyone using the agent connects through that one token. When it expires (after 180 days), or the builder clicks Update in Settings → AI Gateway, everyone's connection will drop until a fresh token is added in Copilot Studio. Worth setting a calendar reminder.
• systemHUB is added but Copilot never uses it
  • Check the tool is switched on in your agent's Tools list, and that the server description clearly says what systemHUB is for.
• Your team can't see the agent
  • Check it has been published (Step 6) and approved by your Microsoft 365 admin (Step 7).
• Can't add the tool, or it's blocked
  • Your organisation's Microsoft data policies may block custom connections. Ask your Microsoft 365 or Power Platform admin to allow it.
• Connector adds but will not connect
  • Remove it and re-add with a freshly generated token.

🎉 You're All Set!

Your Copilot agent can now read your systemHUB content, and your team can use it in Teams and Microsoft 365 Copilot. Try asking it to summarise a system, find a policy, or list what is in a folder.