---
title: "Connect: how to integrate with AI"
description: A step-by-step guide for the engineer who sets up a coding agent to build the Operator Contract, from the first sign-in to the go-live click.
---

For the operator's engineer who wants a coding agent to do the build, and who stays responsible for the parts the agent may not touch.

# How to integrate with AI

This page walks a person through setting up a coding agent (Claude Code, Claude Desktop, Cursor or any MCP client) so it can build your side of the [Operator Contract](/connect/contract). The agent writes code in your repository; you sign in, create the key, review, and click Go live. The agent never can.

## 1. Sign in and open the door

1. Sign in at `https://app.onehazel.com`.
2. Open **Connect casino** in the sidebar.
3. Choose the **Integrate with AI** tab.

Connect is switched on per environment by OneHazel. If the tab loads but your agent later reports `CONNECT_DISABLED`, see [Troubleshooting](/connect/troubleshooting).

## 2. Create the integration key

Click **Create integration key**. The app creates an API key with the Connect tools enabled and shows it **once**, with a warning saying so. Copy it straight into your secret manager or your shell profile as `ONEHAZEL_API_KEY`. Never put it in the repository, a ticket or a chat.

If you lose it, revoke it under **API Keys** and create a new one. Nothing else depends on that exact key.

## 3. Add the OneHazel MCP server to your agent

### Claude Code

Over HTTP, which most clients support:

```bash
claude mcp add --transport http onehazel https://api.onehazel.com/mcp-server --header "Authorization: Bearer $ONEHAZEL_API_KEY"
```

Through the stdio bridge, for clients that only speak stdio:

```bash
claude mcp add onehazel -e ONEHAZEL_API_KEY="$ONEHAZEL_API_KEY" -- npx -y @onehazel/mcp
```

The bridge reads two environment variables:

| Variable | Meaning |
|---|---|
| `ONEHAZEL_API_KEY` | Required. An API key with MCP enabled. Without it the bridge exits with code 2; it never prints the key. |
| `ONEHAZEL_MCP_URL` | Optional. The server the bridge forwards to. Must be https (http only for localhost). |

### Claude Desktop and Cursor

Use the same server URL and key. The configuration files differ per client and are covered step by step on [Connecting Claude Desktop](/mcp/connecting-claude-desktop) and [Connecting Cursor](/mcp/connecting-cursor). Skip their "mark workflows as MCP-exposed" step; it is for workflow tools, not Connect.

The app tab also shows ready-to-paste snippets for Claude Code, Cursor, Codex and the stdio bridge, with your new key already filled in.

**Check:** ask the agent to call `connect_status`. It should answer with one entry per module. If it answers `MCP_CONNECT_NOT_ENABLED` or `CONNECT_DISABLED`, see [Troubleshooting](/connect/troubleshooting).

## 4. Tell the agent what to do

Ask the agent to read the MCP resource `onehazel://skill/integrate` first and follow it. For a setup that survives new sessions, paste the resource `onehazel://agents.md` into your repository's `CLAUDE.md` or `AGENTS.md`. That snippet tells every future session to start with `connect_status`, to read keys only from the environment, and to leave go-live to a person.

## 5. What the agent will do

The agent follows the same track as [Getting started](/connect/getting-started), using the tools listed on [Connect with MCP](/connect/mcp):

1. Calls `connect_status` and `connect_list_marketplace` to see which modules your chosen vendors need.
2. Reads `connect_contract` and `connect_conformance_scenarios` before writing code, so it builds to the checks it will face.
3. Starts from a generated sample (`connect_samples`) in your language and adapts it to your wallet and player store.
4. Asks you to deploy it on a public https address, then registers that address with `connect_register_endpoint`. The response holds the signing secret and, on first registration, the callback key. If your casino mints its own provider keys, the agent can pass yours as `callbackKey` instead. Both are shown once: the agent writes them straight into `<project>/.onehazel/<module>.env` (mode 0600, gitignored) or your deployment secret store, and tells you only the file path and the variable names. It never prints, logs or commits the values.
5. Runs `connect_run_conformance`, reads failures with `connect_conformance_evidence`, fixes, and runs again until the module is conformant.
6. When every required module is conformant, calls `connect_activate` to create the vendor connection **inactive**, and `connect_request_go_live` to notify your team.

## 6. Read the module chips

The **Module status** card shows one chip per module. It refreshes every 30 seconds while the tab is open, and again when you come back to the tab. Hover a chip to see what still blocks it.

| Chip | Meaning |
|---|---|
| Not started | Nothing registered or recorded for this module yet. |
| Registered | An endpoint is registered, but no conformance run has finished. |
| Conformant | The latest finished run passed, or the module's rule is met (see below). |
| Failing | The latest finished run did not pass. The hover text names the run to inspect. |

Not every module is proven by a conformance run. `connect_status` says which with an `evidence` field on each module:

- `run`: the state comes from a finished conformance run (`wallet`, `player`, `webhook.receive` once one has finished).
- `none`: an endpoint module with no finished run yet.
- `derived`: no conformance run exercises the module, so its state is inferred from another signal or is constant.

In `connect_status`, `evidence: derived` means no conformance run backs this module; in v1 that is `launch`, `widget`, `attribution` and `events.push`.

The derived rules are on each module page: [launch](/connect/modules/launch) follows wallet, [widget](/connect/modules/widget) is always conformant in v1, [attribution](/connect/modules/attribution) follows a recorded click, and [events.push](/connect/modules/events-push) follows your first pushed data.

## 7. Go live is a person's click

`connect_activate` only ever creates a connection in the **inactive** state, and `connect_request_go_live` only sends a notification to the active members of your team. No tool, REST route or agent can switch a connection on.

When the **Ready for go-live review** card lists a connection, open it from there, review it, and click **Go live** on the connection page.

## Next

- [Per-module guides](/connect/modules/wallet): what each module is for and what it must pass.
- [Troubleshooting](/connect/troubleshooting): symptom, cause and fix for the common failures.
- [FAQ](/connect/faq): the questions engineers and CTOs ask first.