--- title: "MCP guide: the journey" description: Every step from installing the OneHazel MCP to a live game, who does each one, what the agent is told, and what you should see after it. --- # The journey This page lists every step from an empty folder to the first live game, in order. For each step it says who does it and what your agent is told. It also says what you should see when the step is done. Your agent follows the same list on its own. You only act where a step says **You**. In plain words, the goal is a live vendor connection that a person on your team switched on. OneHazel states it to your agent like this: > The operator is live on OneHazel: every module the chosen connector needs is conformant, the connection exists, and a human has clicked Go live. ::: tip Words on this page - **PAM**: Your casino's own player account system. It holds your players and their balances. - **JSONPath**: A short address, such as `$.data.balance`, that points at one value inside a response. - **dedup**: Short for deduplication: a message that arrives twice is acted on only once. - **X-OneHazel-Env**: A label on every OneHazel call. `test` means test players only; `live` means real players and real money. - **healthz**: An address on the adapter, `/healthz`, that answers 200 while the adapter is running. - **allowUnreachable**: An option that lets your agent register an address before the adapter runs there. - **provider_slug**: The name a game studio has in your casino's game catalogue, such as `acme-studio`. - **game_code**: The id your casino's game catalogue gives one game, such as `book-of-gold`. With `provider_slug` it names your test game. ::: ::: tip What you need before you start - The OneHazel MCP installed in your agent: [Install](/connect/mcp/install). - The items on [Your casino](/connect/mcp/your-casino): your PAM's address, test players, a test game and a host for the adapter. The test game is a `provider_slug` and a `game_code` from your own catalogue: registering the wallet is refused without it. - The vendor you want to go live with first, for example PatePlay. ::: ## How your agent knows what comes next Every answer from a `connect_*` tool carries a `journey` block. It holds the goal, the current stage and the next step. It also lists the steps that remain, and anything waiting on you. In plain words, your agent checks the status first and keeps going until it needs you. Word for word: > Call connect_status first (pass key when your human named the connector), then follow journey.next_step: do not stop while next_step is set, and stop only when journey.blocked_on is set, ask your human its one question, then do what its after_answer says. So your agent works on its own until it needs something from you, then asks one question at a time. The two tables at the end of this page list every question it can ask, and what you do. ## Choosing the connector Before your agent registers anything, it needs the Marketplace connector you want to go live with. Ask your agent to call `connect_list_marketplace`. It returns every public connector, each with the modules it needs, such as `wallet` and `player`. Pick one and reply with its key. You only build the modules that connector needs. Without an agent, the same list is `GET /operators/me/connect/marketplace`, called with your signed-in OneHazel session. You can also browse the connectors on the **Marketplace** page in the app. ::: info What you should see Your agent names the connector and the modules it will register. ::: ## The steps ### Step 1. Install the MCP and paste one line **Who:** You. Follow [Install](/connect/mcp/install), then paste the one line into a new agent chat. ::: info What you should see Your agent calls `connect_status` and reports one line per module, each **Not started**. ::: ### Step 2. Register your wallet and player **Who:** You deploy, your agent registers. OneHazel calls your casino through two modules. `wallet` places bets, pays wins and reads balances. `player` says who a player is and whether they are restricted. Most casinos put the OneHazel adapter in front of their PAM. [Your casino](/connect/mcp/your-casino) explains it. Some vendors also need `webhook.receive`. Your agent tells you when. Your agent writes the adapter's settings. You start the adapter on your host. Then your agent registers its address. Have your test game ready before this step. Registering the wallet is refused without `testGame { provider_slug, game_code }`. Your agent asks for it like this: > Name one active game in your catalogue that may be used for test rounds (provider slug and game code as your PAM knows them) and register it with the wallet as testGame: { provider_slug, game_code }. How to choose it, word for word: > testGame is a game that is ACTIVE in your own catalogue, identified by the same provider slug and game code your launch endpoint accepts. To pick one, ask the person who manages your game catalogue, or use any game a real player can open today. If it is wrong, the wallet probe fails with CONNECT_TEST_GAME_REJECTED and nothing is charged: your casino refuses the session before any bet. It is wallet-only: the player module needs no game and uses testPlayerId and restrictedPlayerId. In short: start the adapter, check it answers, then register. Word for word: > Order: check config, deploy, probe healthz, register. Run the snippet's --check line on every config until each exits 0, then ask your human to run the snippet's Deploy section on the host (deploying the adapter is a human step), confirm both /healthz probes answer 200, then register. OneHazel checks the address answers before it saves it: > Deploy your implementation (or the adapter) first and curl its /healthz yourself, THEN register: connect_register_endpoint probes GET <baseUrl>/healthz and stores nothing on a connection error, timeout or 5xx; pass allowUnreachable: true only to register before deploying. Registering shows your agent two secret values once. It writes them to a private file and tells you only where: > Write the values straight into <project>/.onehazel/<module>.env (mode 0600, gitignored) or the deployment secret store, then tell the human the path and the variable names. Registering the same module again later, for example to fix its address or its test game, keeps these two values. So that fix needs no restart. Word for word: > Registering a module that is already registered keeps its signing secret and callback key (the result says secretUnchanged: true and carries no secret), so fixing an address, a test player or the test game this way changes only OneHazel's registration and needs no adapter restart; only connect_rotate_secret, or a different callbackKey, replaces them. When your agent registers a module again, it passes every stored input again. `connect_status` returns the stored inputs for each module, so your agent reads them back first and reuses what it returns. ::: info What you should see The **Module status** card shows `wallet` and `player` as **Registered**. Your agent tells you the file paths and the variable names in them, never the values. ::: ### Step 3. Copy the values and restart the adapter **Who:** You. Registering made a signing secret and a callback key for each module. Your agent wrote each module's values to its own file under `.onehazel/`, one env file per module. Your adapter still runs with the stand-in values, so every test call would be refused with 401. So your agent registers every module first, then waits for you before it tests anything. It is told: > Ask your human to copy every newly registered module's values from .onehazel/<module>.env into onehazel.env on the adapter's host and restart the adapter; run conformance only after they confirm, or every call answers 401 against the stand-in values. It asks you, word for word: > Please copy the new values for \[module\] from the .onehazel folder (one env file per module) into onehazel.env on the adapter's host, restart the adapter serving \[adapter host\] (with Docker, run the start line again plus --force-recreate; without Docker, stop the adapter process and run its npx start line again with the new values in the environment; the person who deployed the adapter in step 4 of Your casino restarts it; the compose file and onehazel.env are in the folder created in step 2 of Your casino on that host), and tell me when both /healthz checks answer 200 again. The values are meant to live in those private files and in `onehazel.env` on your host. Keeping them there never calls for a rotation. Copy the values into `onehazel.env` on your adapter's host, in place of the stand-in values. Then restart the adapter: step 5 of [Your casino](/connect/mcp/your-casino) shows the line, with Docker and without. One process serves every module, so you restart once. ::: info What you should see Both `/healthz` checks answer 200 again. You tell your agent, and it starts a test run for each module. ::: ### Step 4. Pass conformance **Who:** Your agent. Your agent asks OneHazel to test each module. OneHazel sends the same calls a vendor would, with test players only. It records every request and every answer. Your agent reads the failures, fixes the settings, and runs the test again. It can run at most 10 tests an hour. The adapter reads its settings file and `onehazel.env` only when it starts. So when a fix changes either one, your agent first asks you to restart the adapter. A fix it makes by registering again, such as a new address, test player or test game, changes only OneHazel's registration and needs no restart. A `testGame` changed in the settings file does. It is told: > If your fix changed onehazel-adapter.json or onehazel.env (testPlayerIds after env_refused, the player route, the wallet testGame, a module section missing behind 404 no such route), the adapter only reads them when it starts: ask your human to restart it (with Docker, run the start line again plus --force-recreate; without Docker, stop the adapter process and run its npx start line again with the new values in the environment) and confirm both /healthz checks answer 200 before you run conformance again. A fix made only by registering again (an address, a test player or the testGame) changes only OneHazel's registration and needs no restart; the same testGame changed in onehazel-adapter.json needs the restart. A module that already shows **Conformant** keeps that state after a re-register that changes no secret. Conformance does not need to run again unless `connect_status` reports the module failing or not started. ::: info What you should see The **Module status** card shows each module your vendor needs as **Conformant**. ::: ### Step 5. Play one simulated round (optional) **Who:** Your agent. Your agent plays one pretend round against your wallet: a bet and a win for your test player. It proves money moves the right way before any vendor is involved. You can skip it. > **What your agent is told:** Optional: play one simulated round against the wallet with connect_simulate (scenario round). Skipping it does not block go-live. ::: info What you should see Your agent reports the round's result, and your test player's balance shows the bet and the win. If your agent says your casino refused the test game, see the table at the end of this page. ::: ### Step 6. Create the connection (inactive) **Who:** Your agent. Your agent creates the connection to the vendor you chose. It is created switched off, which OneHazel calls inactive. Nothing can reach your players yet. > **What your agent is told:** Create the INACTIVE connection for the connector with connect_activate. ::: info What you should see The connection appears on the **Connections** page with the status **Inactive**. When every module it needs is conformant, the **Integrate with AI** tab also lists it under **Ready for go-live review**. Some vendors need this connection's id now; the vendor's page says so. ::: ### Step 7. Add the vendor's keys **Who:** You give the values, your agent saves them. Or you type them yourself. The vendor issues a few values when they set up your site, for example an API key and a secret. Each vendor's page says which values and where the vendor gives them: for PatePlay, step 1 of [PatePlay](/connect/mcp/providers/pateplay). They go on the connection and nowhere else. Some vendors issue these values only after your casino gives them the connection's address. PatePlay is one. If your vendor needs your address first, give it that before you ask for the values. Your agent asks you for each one by its field name and saves them with `connect_set_credentials`. If you would rather not type them into the chat, type them yourself on the connection's **Credentials** tab: the [go-live page](/connect/mcp/go-live) shows where. > **What your agent is told:** Set the connector's vendor credentials on the inactive connection with connect_set_credentials. Vendor credentials: ask your human for each value once, by its field name, pass the values straight to connect_set_credentials, and never print, log, echo or commit them; the response returns only field names. ::: info What you should see Your agent reports the field names it saved and any still missing, never the values. The connection is still **Inactive**. ::: ### Step 8. Ask for the go-live review **Who:** Your agent. Your agent tells your team the connection is ready to be checked. This sends a notification and changes nothing else. The tool reports `ready` and `missing`. If anything is missing, such as a vendor value, it still notifies your team. But the review is not ready, and the journey does not advance. > **What your agent is told:** Open the go-live review with connect_request_go_live; it notifies the team and changes no status. ::: info What you should see The active members of your team get a notification. The connection is still **Inactive**. If your agent reports `ready` as false, set what `missing` lists and ask for the review again. ::: ### Step 9. Replace any key that was shown in chat **Who:** Your agent. A OneHazel callback key or signing secret may have been exposed. That means pasted into a chat, printed in a log, committed, or written to a file that is not private. A private file has mode 0600 and is ignored by git. If so, your agent rotates that module's key and secret with `connect_rotate_secret`. The old values keep working for one hour. The values are meant to live in the private file under `.onehazel/` and in `onehazel.env` on your host. Keeping them there never calls for a rotation. If nothing was ever exposed, this step does nothing. > **What your agent is told:** If a callback key or signing secret was ever printed, logged or committed, call connect_rotate_secret with {"module":"<that module>","what":"both"} before you stop; write to a 0600 file inside your workspace, never print. The previous values stay accepted for 1 hour, so update the adapter from save_as within that hour. ::: info What you should see Your agent says nothing needed replacing, or it tells you the file path and the variable names of the new values. Put the new values on your adapter's host and restart the adapter within the hour. ::: ### Step 10. Click Go live **Who:** You. No tool can do this. A person on your team opens the connection and switches it on. The [go-live page](/connect/mcp/go-live) shows every click. > **What your agent is told:** Wait for a human to click Go live on the connection in the OneHazel app. ::: info What you should see The connection's status changes from **Inactive** to **Active**. Ask your agent to call `connect_status`: the journey says it is complete. ::: ### Step 11. Play the first game **Who:** You. Your connection is live, so the connection, the keys and Go live are done. What is left is vendor-specific: the address you give the vendor, its games in your catalogue and the first spin. Each vendor's page covers only those parts. For PatePlay, follow [PatePlay](/connect/mcp/providers/pateplay) from step 2. ::: info What you should see The game opens. Your casino's records show the bet, and any win, against that player's balance. ::: ## When your agent stops and asks you Your agent asks at most one question at a time. ### While it writes the settings and registers (step 2) Your agent asks for these in its own words, except the test game, which it asks word for word. | Your agent asks for | What you do | |---|---| | Your PAM's address: the full path to its provider routes, not only the host name. | Give the address. [Your casino](/connect/mcp/your-casino) shows the rule. | | The header your PAM expects from a trusted service, such as `Authorization`. | Name the header. Never type the token itself into the chat: you put it in the env file on your host, in step 4 of [Your casino](/connect/mcp/your-casino). | | The adapter's public https address. | Give the address your host serves the adapter on. One adapter serves every module, so it is the same address for each module. | | A test player id, `testPlayerId`. The adapter lists the same ids in its settings as `testPlayerIds`. | Give the id of a player in your test setup with money in its test balance. | | A restricted test player id, `restrictedPlayerId`. Only for `player`. | Give the id of a second test player with an active limit, block or self-exclusion. | | Name one active game in your catalogue that may be used for test rounds (provider slug and game code as your PAM knows them) and register it with the wallet as testGame: { provider_slug, game_code }. | Give the provider slug and game code of a game that is active in your catalogue and allowed for test players. This is `testGame`, only for `wallet`: registering the wallet is refused without it. | | Only for `webhook.receive`: the address in your PAM that accepts OneHazel's events, its event sink. Not needed for PatePlay. | Give the full https address. The adapter delivers each event there as `sink.url` in its settings. | | Only for `webhook.receive`: a Redis address for dedup. Not needed for PatePlay. | Put a `redis://` or `rediss://` address in `onehazel.env` as `ONEHAZEL_ADAPTER_REDIS_URL`. Tell your agent only that it is set, because a Redis address often carries a password. [Your casino](/connect/mcp/your-casino) shows the options. | ### When it stops on a blocked step The parts in brackets, such as `[module]`, are filled in with your real values when it asks. `[connection path]` is a path in the OneHazel app, not a full link. The questions are quoted word for word. Two test-game questions read the same: the **When** column tells them apart. | When | Your agent asks | What you do | |---|---|---| | Before it registers anything, if you have not named a vendor | Which marketplace connector (a key from connect_list_marketplace) should this casino go live with? | Reply with the connector's key, for example `pateplay`. If you do not know it, ask your agent to list the marketplace. | | When it registers, if nothing answers at the address | Please start the adapter on your host (one process serves every module) or deploy your implementation of \[module\], and confirm GET \[base URL\]/healthz answers 200. | Start the adapter on your host: one process serves every module, with one settings file. Run the two `/healthz` checks on [Your casino](/connect/mcp/your-casino), then tell your agent both answered 200. | | After it has registered every module, before any test run | Please copy the new values for \[module\] from the .onehazel folder (one env file per module) into onehazel.env on the adapter's host, restart the adapter serving \[adapter host\] (with Docker, run the start line again plus --force-recreate; without Docker, stop the adapter process and run its npx start line again with the new values in the environment; the person who deployed the adapter in step 4 of Your casino restarts it; the compose file and onehazel.env are in the folder created in step 2 of Your casino on that host), and tell me when both /healthz checks answer 200 again. | Copy each module's values from its file under `.onehazel/` into `onehazel.env`, in place of the stand-in values. Restart the adapter: step 5 of [Your casino](/connect/mcp/your-casino) shows the line, with Docker and without. Tell your agent once both `/healthz` checks answer 200. | | After a simulated round | Please name one active game in your catalogue that may be used for test rounds (provider slug and game code as your PAM knows them), because your casino rejected the testGame registered with the wallet. | Tell your agent the provider slug and game code of a game that is active in your catalogue and allowed for test players. It registers that game and plays the round again. Registering again changes only OneHazel's registration, so you do not restart the adapter; if your agent also changes testGame in onehazel-adapter.json, restart the adapter. Or tell your agent to skip the simulated round: it is optional. | | After a test run | Please name one active game in your catalogue that may be used for test rounds (provider slug and game code as your PAM knows them), because your casino rejected the testGame registered with the wallet. | Tell your agent the provider slug and game code of a game that is active in your catalogue and allowed for test players. It registers that game and runs the test again. Registering again changes only OneHazel's registration, so you do not restart the adapter; if your agent also changes testGame in onehazel-adapter.json, restart the adapter. | | When your vendor needs `events.push` | Please start sending this casino's real player or event data to OneHazel, because events.push is proven only by the first real record. | Start sending your casino's real player or event data to OneHazel. Never invent data to pass this step. | | When your vendor needs `attribution` | Please install the OneHazel affiliate tag on the casino site so the first tagged visit can land. | Install the OneHazel affiliate tag on your casino site ([Affiliate tag](/connectors/attribution-tag)), then open the site once through a tagged link. | | At the end | Please open \[connection path\] in the OneHazel app, check the connection and its vendor credentials, and click Go live. | Your agent gives a path such as `/operator/connections/conn_1a2b3c4d5e6f`, not a full link. Open `https://app.onehazel.com` followed by that path, or open **Connections** and click the connection. Then follow [Go live](/connect/mcp/go-live). | Anything else stopping your agent? See [Troubleshooting](/connect/mcp/troubleshooting).