Connect an AI assistant and ask it how to use ONYX1

Your assistant works as you: it sees and does only what your role allows, and ONYX1 records what it reads and does. This article covers 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 claude.ai 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 claude.ai

Do these steps yourself, in your own claude.ai 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 step for claude.ai.
2. When claude.ai 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: claude.ai connects straight away.

Connect a desktop app such as Claude Desktop or Cursor

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 "My Claude".
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.

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.