Skip to content

Connect an AI assistant and ask it how to use ONYX1

Connect a browser-based assistant, desktop app or ChatGPT workspace app to ONYX1, then ask it about your visible work or how to use the app.

For owners, office staff and crewAvailable on Pro and EnterpriseLast reviewed
On this pageBefore you start

Your assistant works as you: it sees and does only what your role allows, and ONYX1 records what it reads and does. This article explains how to connect a browser-based AI app or a desktop app, including claude.ai, Claude Desktop and Cursor.

Before you start

  • Your workspace's plan must include AI & integrations. The labels at the top of this page say which plans do.
  • Anyone in the workspace can connect an AI assistant for themselves.
  • Only the owner and admins can connect a desktop app, because the token for it comes from Settings → AI & integrations.
  • If your business requires two-factor sign-in and you haven't set it up, ONYX1 asks you to set it up first.

What your assistant may do

You choose one of three levels when you connect:

  • Read only: see jobs, customers and the schedule, and change nothing.
  • Read + everyday actions: also create and update jobs, notes and the day-to-day.
  • Read + money / sensitive actions: also invoices, quotes and other money or irreversible actions. Only the owner, admins, dispatchers and office staff are offered this level.

Whatever the level, the assistant can't do more than your role allows. Before a money or irreversible action runs, ONYX1 hands your assistant a plain read-back of it, such as the invoice and its amount, and runs it only once the assistant confirms that exact action. Check the read-back when your assistant shows it to you.

Owner safety-document review

An owner can use a connected assistant to review the current safety documents through ONYX1. When Owner approves safety documents before a job is scheduled is on, the assistant can also show the safety approvals queue and carry out an approval decision. You do not need to download the PDFs.

Ask it to:

  • show the safety approvals queue
  • read the SSSP and Rescue Plan for a job number, such as JOB-0042
  • approve the documents after you have reviewed them
  • request changes and give it the note to record
  • mark the job as not requiring safety documents and give it the reason

The assistant reads the current PDFs on the ONYX1 server. When text is available, it returns up to 20,000 characters from each PDF and 40,000 characters across the response, labelled as document content and not instructions. A scanned or image-only PDF is reported as having no text layer and, when available, its page count. No OCR is run. If text extraction is unavailable, ONYX1 says so instead. The assistant identifies the exact document versions you reviewed. If someone replaces a document before you decide, ONYX1 refuses the decision and asks you to read the current pair again.

The safety-document tools are owner-only. Admins, dispatchers, office staff, site supervisors, technicians, contractors and portal or customer connections cannot see or use them. Approving, requesting changes or marking documents not required needs the Read + money / sensitive actions connection level and a confirmation from you. Every read and decision is recorded in the ONYX1 audit log.

Connect an AI assistant

Do these steps yourself, in your own AI app account.

  1. In your AI app, add ONYX1 as a custom connector using the ONYX1 server address: the address you open ONYX1 at, followed by /api/mcp. If you open ONYX1 at onyx1.app, it's https://onyx1.app/api/mcp. ONYX1's Settings → AI & integrations gives the same address.
  2. When the AI app sends you to ONYX1, sign in if you're asked to.
  3. On Connect your AI, check the address after Your connection will be sent to. It should be the AI app you started in; if you don't recognise it, select Cancel.
  4. Under What this AI may do, select a level.
  5. Select Approve & connect.

There's no token to copy for this connection. The AI app connects after you approve it.

If your workspace has the ONYX1 Office add-on, Settings → AI & integrations has an ONYX1 Office section. It explains the two ONYX1 addresses. The ONYX1 connector (/api/mcp, the address above) gives your assistant your own ONYX1 data. The ONYX1 Office address (/api/mcp/office) connects your assistant to the digital office team and its approvals. The section links to Settings → ONYX1 Office, where the address and its steps appear once your Office server is online. See ONYX1 Office.

Follow Office requests

To check a running request, give its ID to get_work_status. The Office page shows the current status, recorded activity, approvals, result and any file links. ONYX1 requests an in-app notice when work you send to Office is completed; your notification settings control whether it appears. See ONYX1 Office.

Create a document

Through your connected assistant, you can ask ONYX1 Office to prepare a Word document, PDF, Excel workbook or flyer using ONYX1 information you can access. For example, ask, “Create a PDF of my timesheets.” You can also ask for an investigation summary with its source references. The result includes the file name and a private ONYX1 Resources link. ONYX1 checks your access each time you open it. Files are not emailed or sent outside your business. See Create a document in ONYX1 Office.

Connect ChatGPT in a Business workspace

This setup is for a ChatGPT Business workspace and is done by an admin or owner in ChatGPT web. OpenAI's developer mode and MCP apps guide (opens in a new tab) has the current steps.

  1. Open Workspace Settings → Apps → Create. Enable developer mode when ChatGPT prompts you. In a Business workspace, only an admin or owner can enable it.
  2. Enter the ONYX1 MCP endpoint from Settings → AI & integrations and the required metadata for the server.
  3. Choose OAuth, then select Scan Tools. When ChatGPT opens the ONYX1 sign-in page, sign in and select Read only. Wait for the tool scan to finish.
  4. Select Create. The app is saved as a draft under Workspace Settings → Apps → Drafts.
  5. Open a new chat, select the draft app from the tools menu, and try a read-only request, such as asking which jobs you can see. Check that the answer contains only information your ONYX1 role can access.
  6. After ONYX1 adds refresh-token support, create a new app draft with the updated server metadata, scan its tools and repeat the read-only test. An admin or owner can then publish the tested app from Workspace Settings → Apps → Drafts by selecting Publish.

For ongoing access, OpenAI recommends that an OpenID Connect provider request the offline_access scope, advertise support for it in discovery metadata, and issue a refresh token. If the scope is missing or no refresh token is returned, the provider needs refresh access enabled. After the provider is updated, create a new app draft so ChatGPT can read the updated metadata, then scan and test that draft before publishing. This is a provider setting, not a ChatGPT app setting. ONYX1's current OAuth service does not advertise offline_access or return refresh tokens, so it does not yet meet this recommendation. A successful read-only test does not verify that the connection can refresh.

Do not publish the ONYX1 app for regular use until ONYX1 supports refresh tokens.

Connect a desktop app

The owner or an admin does these steps.

  1. Open Settings → AI & integrations.
  2. Under Connect your AI (MCP), type a name for the connection, for example "ONYX1".
  3. Select what it may do: Read-only, Read + everyday actions or Read + money/sensitive actions.
  4. Select Connect.
  5. Copy the MCP server URL and the Token straight away. The token won't be shown again.
  6. In your app's MCP settings, add a server with that URL and send the header Authorization: Bearer <token>, putting your token in place of <token>. The Settings page names mcp-remote --header as one way to send it.

Ask it how to use ONYX1

Ask your assistant things like "how do I add a staff member?". ONYX1 gives it these help articles and tells it to answer only from them, to give you the link to the article it used, and to say plainly when the help centre doesn't cover your question. If your app lists prompts, you can also select how_do_i and describe what you want to do.

The assistant is a separate app, so ONYX1 can't make it follow those instructions. If an answer looks wrong, check the linked article.

Disconnect an assistant

Only the owner and admins can disconnect an assistant in ONYX1. If you want yours disconnected, ask one of them.

  1. Open Settings → AI & integrations.
  2. Under Connected AI clients across your team, select Disconnect beside the connection, and confirm.

If the connection belongs to someone else, ONYX1 tells them it was disconnected.

Every request is recorded

Each tool an assistant uses, and each record, article or prompt it reads, is recorded in the Audit log, under the Settings hub, marked AI. The owner, admins, dispatchers and office staff can read it.

Mention AI in your privacy policy

If your team connects an AI assistant to ONYX1, add these sentences to your business privacy policy. Name the AI service your team uses if it is not Claude.

We use ONYX1 to manage our jobs and records. Our team uses AI tools with ONYX1, including Claude, to help with that work, so the AI provider may process your details, including outside New Zealand.

If something goes wrong

  • Can't connect with the message AI & integrations isn’t on your workspace’s plan. Your plan doesn't include it. An owner can change the plan in Settings → Plan & billing. See Plans and what each includes.
  • When you select Connect, ONYX1 says Your plan doesn’t include AI & integrations. The cause and the fix are the same.
  • An assistant that was working stops answering after a plan change: the new plan doesn't include AI & integrations.
  • Settings → AI & integrations is missing: your plan doesn't include AI & integrations (see above), or an owner hid it in Settings → Features. Assistants already connected keep working when it is hidden. See Show or hide features.