Connect your AI assistant #

View this page as Markdown

On this page

This page describes how to connect your AI assistant to Turn Zero Cloud yourself. To have your AI assistant do it for you, paste the prompt from Set up Turn Zero Cloud instead.

Choose the address for your AI assistant:

  • For Claude Code or Codex CLI, including a desktop or editor sharing its configuration, use https://turnzero.ai/mcp named turnzero for tzCloud, tzTrack and tzMesh.
  • For a chat app using Turn Zero Cloud, use https://tzcloud.turnzero.ai/mcp named turnzero-hosting for tzCloud.
  • For a chat app using tzTrack or tzMesh, use https://tztools.turnzero.ai/mcp named turnzero-tools for tzTrack and tzMesh.

Your account’s access still limits the tools you can use. Your first sign-in can create a free Turn Zero account. Each address has its own sign-in; connecting to one does not connect the others. A desktop or editor that shares the CLI configuration reuses turnzero; add no second connection there.

The connection lists tzCloud tools as tzcloud_<name>; for example, "deploy" is tzcloud_deploy. If a listed tool returns "Unknown tool", refresh the connection.

Already connected? If your AI assistant has a signed-in connection with tzCloud tools, go to Check the connection.

Reuse it if it is signed in and provides tzCloud tools; check its address before changing or removing it.

If you use Steps
Claude Code, in a terminal or the Claude desktop app's Code tab Claude Code
Codex: the CLI, the ChatGPT desktop app, or an editor Codex
Claude's chat (claude.ai, the desktop app, the phone app), or Claude Code on the web Claude's chat and Claude Code on the web
ChatGPT on the web, or Codex in ChatGPT's cloud ChatGPT and Codex in ChatGPT's cloud
An AI coding agent that runs with nobody at the keyboard, such as a scheduled run Connect an unattended AI coding agent with a token

After your assistant's steps, sign in and check the connection. An unattended AI coding agent has no browser sign-in; its section says how it checks the connection.

What each sign-in lets you do #

Signing in to the website, connecting your AI assistant, and authorizing the turnzero command give access in different places. Use this table to see which connection your task needs.

Sign-in or credential What it lets you do What it does not do
Your browser sign-in on turnzero.ai Use your account's dashboard and approve actions that ask for your approval. Signing in from the website's header does not connect your AI assistant or authorize the command on your computer.
Your AI assistant's MCP connection, signed in through the browser Create and configure applications, deploy through the connection, and mint tokens for commands or unattended jobs, within your account's access. It does not store a credential for the command on your computer. Your AI assistant can authorize the computer through this connection.
Device sign-in to the MCP connection Use tzTrack and limited account and documentation tools after approving a code in a browser on another device. It cannot manage or deploy Cloud applications, mint tokens, or use Cloud storage and outbound-request services. For Cloud management, use the browser sign-in above or a minted token.
The computer token stored by turnzero login, login --device, or authorize Run commands such as turnzero check and turnzero deploy for an existing application, and take library packages. It does not sign your AI assistant's MCP connection in. Creating the application and submitting its manifest still need MCP; prepare an unattended deploy describes the setup.
A minted token kept for an unattended job Use the actions allowed by its scope and grants, through a token-connected MCP client or commands that accept TURNZERO_CLOUD_MINTED_TOKEN. A token for one application cannot create another application. No minted token can mint another token. Configuring the MCP connection does not also supply the token to a command.
Your application's platform credential, TURNZERO_CLOUD_APP_TOKEN Let the backend use its own environment's services, such as storage, logs and outbound requests. Turn Zero supplies it to the deployed backend. It cannot connect an AI assistant or authorize a deploy command. It is separate from your account's sign-in and your application's users' sessions.

turnzero login --device authorizes the command on the requesting computer. It is different from device sign-in to the MCP connection, which has the limits in the third row.

For credential lifetimes, revocation, application users' sessions and keys for external APIs, see Sign-in, sessions, and tokens.

Claude Code #

To connect and build in one Claude Code session, run this in your own terminal before you start Claude Code. It adds the connection for every folder on this computer:

claude mcp add --transport http --scope user turnzero https://turnzero.ai/mcp

On Windows, if PowerShell says claude is not recognized, the native installer's folder may be missing from PATH. If %USERPROFILE%\.local\bin\claude.exe exists, add %USERPROFILE%\.local\bin to your user Path as a new entry, keeping the existing entries. Reopen the terminal; if it is inside an editor, restart the editor too. Run claude --version, then retry the connection command above. If the file is missing or the command still fails, follow Claude Code's PATH troubleshooting.

Start Claude Code. When it needs a sign-in, its notice tells you to run /mcp. Type /mcp, choose turnzero, and complete the browser sign-in. You can build in that same session.

If your AI runs the add command from a session instead, start a new Claude Code session before signing in. The session where your AI ran the command does not pick up the tools.

In the Claude desktop app's Code tab, /mcp opens the app's connector settings, which do not list a server added with claude mcp add. Sign in from a terminal instead: run claude, type /mcp, choose turnzero, and complete the browser sign-in. Or add it by hand with the connector steps below.

A new desktop Code tab session can reuse the terminal connection. If you choose the custom connector instead, remove the terminal entry with claude mcp remove turnzero first.

In the Claude desktop app's Code tab, a connector can appear under its ID rather than its name. Its instructions identify the Turn Zero connection.

Codex #

Run this in a terminal:

codex mcp add turnzero --url https://turnzero.ai/mcp

It opens your browser to sign in. If it doesn't, run codex mcp login turnzero. Then start a new chat.

If the desktop app or editor shares your Codex CLI configuration, reuse turnzero. Otherwise, in the ChatGPT desktop app, open Settings → Plugins → Add → Add MCP server. Enter turnzero-hosting as the name and choose Streamable HTTP (the form starts on STDIO). Enter https://tzcloud.turnzero.ai/mcp as the URL, leave the token and header fields empty, and choose Save. In the MCPs list, choose Authenticate beside turnzero-hosting and sign in in your browser. Then start a new chat.

Claude's chat and Claude Code on the web #

Follow these steps yourself. Your AI checks the connection after you finish signing in.

  1. On claude.ai, open Settings → Customize → Add → Add custom connector. In the Claude desktop app, open Settings → Customize → Connectors, then choose Add → Add custom connector.

  2. Enter the name and URL below. On claude.ai, the URL field is MCP Server URL. The desktop app labels it MCP server URL.

    Name:

    turnzero-hosting
    

    URL:

    https://tzcloud.turnzero.ai/mcp
    

    Choose Continue.

  3. Keep Sign in now, choose Register automatically under OAuth client, and leave Request headers empty.

  4. Choose Add, sign in on the Turn Zero page that opens, and choose Allow access. If you recently signed in, the sign-in page may be skipped; choose Allow access if the access page appears.

  5. In your chat, open + → Connectors and check that turnzero-hosting is on. On claude.ai, keep the same conversation. Then ask your AI to check the connection.

If Claude says this connector already exists, Turn Zero Cloud is already added to your account, so you don't need to add it again. Go to step 5 and check that turnzero-hosting is on. On a Team or Enterprise plan, an owner adds the connector under Organization settings → Connectors, and each member chooses Connect.

Claude's Free plan allows one custom connector, as Anthropic's instructions state.

ChatGPT and Codex in ChatGPT's cloud #

Your ChatGPT account must allow adding and using a custom MCP server. In a company workspace, your administrator controls the permissions that may be required.

  1. Open Settings → Plugins → Browse directory → Add → Add custom MCP server.
  2. Enter turnzero-hosting as the name and https://tzcloud.turnzero.ai/mcp as the URL. Keep OAuth.
  3. Check the address in the warning, choose I understand and want to continue, and choose Create as a plugin.
  4. If Install is offered, choose it. Then choose Connect turnzero-hosting, sign in, and choose Allow access.
  5. In ChatGPT, switch to Work and start a new chat. Type @, select turnzero-hosting, and ask it to use Turn Zero Cloud.

The plugin also appears in the ChatGPT desktop app (Codex), signed in, so you don't need to add it there again.

If Add custom MCP server is missing or blocked, ask your workspace administrator whether you can add Turn Zero. You can instead use Claude Code or Codex on your computer, where your company's policy permits it.

Signing in #

You make the first sign-in yourself, in a browser: your AI assistant can't do it for you. Turn Zero's sign-in methods are GitHub, Google, or a code sent to your email. If you signed in to Turn Zero in the same browser in the last 8 hours, you may not be asked again.

The page that follows names the tool asking for access, such as claude.ai, and your account. Choose Allow access only if you just started that connection.

Once you are signed in, ask your AI assistant to file feedback about anything that went wrong before sign-in.

Connecting doesn't let the turnzero command deploy from your computer; that is a separate step, Authorize this computer for deploys.

Check the connection #

Ask your AI assistant: "Check my Turn Zero Cloud connection." It should call start, give your account’s standing, such as active, and check that tzCloud tools are available. A working start alone does not establish that the connection provides hosting tools.

Try it #

After connecting and signing in, paste this prompt into your AI assistant. It creates and deploys a small app in your account.

Create a small hello-world web app and deploy it.

If something goes wrong #

What you see What to do
Your AI coding agent refuses to run the mcp add command, for example in Claude Code's auto mode Run the command for your tool from the steps above in your own terminal, then sign in. Don't rewrite the refused command or change the AI coding agent's permissions.
Your AI assistant lists Turn Zero's tools, but a call returns "Unknown tool" The AI assistant has a stale tool list. Refresh the connection or restart the AI assistant, then check the connection again.
A call returns "No such tool available" Your AI assistant may add the connection's name to each tool's name. In Claude Code, read_documentation is mcp__turnzero__read_documentation. Use the name your tool lists.
The browser sign-in finishes but the tool still shows disconnected Retry its sign-in once, using the address in your tool's setup steps above. Don't paste tokens or browser addresses into its settings.
Claude says the connector already exists Turn Zero Cloud is already added. Don't add it again: in a chat, open + → Connectors and check that turnzero-hosting is on.
ChatGPT says an app with this name already exists You added it before. Open Settings → Plugins → Browse directory → Personal and choose + beside turnzero-hosting.
A connector added with a setting other than Sign in now won't connect That setting can't be changed. Remove the connector and add it again.
invalid_client, or a page titled Connect your tool again Your tool's registration expired. Remove the connection and add it again.
Your AI assistant cannot file feedback before sign-in After signing in, follow the feedback step above.
Codex asks which client registration to use, or its sign-in fails while registering the client Run codex mcp login turnzero --oauth-client-registration dcr.

Setup troubleshooting covers more problems, and Refusals lists every refusal by name.

Refresh or remove the connection #

To reload the available tools:

  • On claude.ai, open the connector's … menu and choose Refresh tools list. Keep the same conversation. After the refresh finishes, ask your AI to reload its tool list if it can and check the connection.
  • In Claude Code, type /mcp, or start a new session.
  • In ChatGPT, choose the connector's Refresh, then open a new chat.
  • In another AI assistant, start a new session or restart it.

To end the connection without deleting your account or apps, choose Disconnect beside your AI assistant on the dashboard's Connected AI tools page (Read and end connections).

An AI assistant whose logout revokes its sign-in ends that connection at once when it sends the refresh token or an access token that has not expired. Removing only the assistant's stored copy leaves the connection live on Turn Zero. Disconnect ends it for any AI assistant. To remove the assistant's copy:

  • Claude Code: claude mcp remove turnzero
  • Codex: codex mcp logout turnzero, then codex mcp remove turnzero
  • Claude's chat: open Connectors as in Claude's chat and Claude Code on the web, select the connector, open its … menu, and choose Remove.
  • ChatGPT: manage it on ChatGPT's Plugins page.
  • ChatGPT desktop app: Settings → Plugins → MCPs.

For your AI #

When you connect for the person, follow Set up Turn Zero Cloud.

Before you start #

Check the connection before building or deploying an application.

If a listed tool returns "Unknown tool" on claude.ai, ask the person to choose Refresh tools list in the connector’s menu. Wait for confirmation. Then reload your tool list if your client supports it and check the connection in the same chat.

  • With permission to change the connection, you can run the CLI add command for Claude Code or Codex if your tools allow it. The person completes the browser sign-in. In Claude Code, ask them to start a new session, type /mcp there and choose turnzero. In Codex, ask them to finish the sign-in opened by codex mcp add, or run codex mcp login turnzero if no browser opened. In claude.ai, give the person the connection steps above; you cannot perform them from the chat. Do not start a login where the person cannot see it.
  • If your permissions refuse the mcp add command, give the person the exact command for their tool from the steps above to run in their own terminal, then ask them to sign in. Never rewrite the command or suggest changing permissions. If a Turn Zero tool you can see returns "Unknown tool", your tool list is stale: ask the person to refresh the connection or to restart you, then check the connection again.
  • A request before sign-in returns status 401 and changes nothing. Ask the person to finish signing in, then retry.
  • Read How an AI reads these docs to read a page whole, one section at a time, or by search.
  • Without a shell, deploy with deploy_files, as Deploy from a chat describes.
  • Call start first. Report the account and its standing when it succeeds. If it is refused, call read_account and report those details from that answer instead. An application-scoped token cannot call start; token_scope_refused does not mean it needs a new sign-in. Report the refusal if neither read succeeds.
  • When you need to find a tool, call read_context with id: "tools" and limit: 16000. The index starts with the path for reading Turn Zero Cloud tools' reference pages through read_documentation, then lists each Turn Zero Cloud tool's name and opening sentence, a long one shortened at a word. Its last line names the entry for each other product's tools, such as id: "tools:tztrack". Read the overview with read_context when a task needs a platform rule you do not know.
  • When start succeeds, its credential field identifies the connection's credential and says whether it may create and sign in test end users on production.
  • Use start's versions to check which build served you. server and tzcloud give the full build commit, also returned as serverInfo.version by MCP initialize. tztrack and tzmesh give the last version read from each product's MCP handshake. Each of those two keys appears only if this connection lists that product's tools and the server has read its version. Quote the full build commit in a report so it can be matched to the report's seen_in.version.
  • Connecting does not write project files or require platform approval. Authorizing a computer stores its credential outside the project.
  • Use dynamic client registration where Codex offers the choice: codex mcp login turnzero --oauth-client-registration dcr.
  • For unattended runs, first establish a signed-in connection. Call mint_token, have the person run the returned token claim command into the run's secret store, and set the stored value as TURNZERO_CLOUD_MINTED_TOKEN. See Mint a token.

Authorize this computer for deploys #

The turnzero deploy, library take, and scaffold commands use a credential stored on the computer or supplied for the command.

Choose how to deploy with Ways to deploy to Turn Zero Cloud. With a shell, try npx --no-update-notifier -y turnzero@latest --version once before deciding npx cannot run here. Use npx.cmd on Windows. Do not skip this check on a session note or a guess about the network. No global installation is needed.

If the command cannot reach turnzero.ai or the npm registry, explain that the tool's setting for its shell's network access controls this. A change to that setting takes effect in a new chat. Ask the person before switching to deployment through deploy_files. Deployment with the command supports the scaffold's tests and a local run; deploy_files alone provides neither.

If npx can't run here, use the installed command where turnzero --version responds. Otherwise, for a deploy use deploy_files within its limits, then the upload route past them. Install the command only if the person wants to keep it.

Authorize this computer through your signed-in MCP connection:

  1. Run npx --no-update-notifier -y turnzero@latest authorize with nothing sent to its standard input. On Windows, use npx.cmd in place of npx.
  2. Call mint_token with the arguments that command prints.
  3. Run its returned command_npx, or command_npx_windows on Windows, once, as given, on that same computer. It stores the computer's credential.
  4. Tell the person the credential's label, its 30-day expiry, and how to revoke it.

mint_token returns npx and installed forms of authorize --mint <id>. It adds --origin for another platform address, including Turn Zero's development platform. Both forms use the same credential file on this computer. The id names the pending token request and is not a credential.

The earlier authorization command saved a random secret on this computer, called the verifier. The returned command uses that secret to complete the request once. It contains no code to copy or pipe. authorize refuses a code piped into it.

If your permissions block npx, the installed command, installation, mint_token, or its returned command, follow the available routes in Ways to deploy and tell the person which you take and why.

If authorization is refused and no available deploy route works, ask the person to run turnzero login in their own terminal. Give the browser-login steps below, one step at a time.

For a refused deploy or upload command, give the person that exact command only after the available routes cannot complete the deploy. Never rewrite a refused line or suggest changing permissions.

Claude Code's auto mode blocked an older command, which piped a code; this command holds none. A connection using a minted token cannot call mint_token; supply TURNZERO_CLOUD_MINTED_TOKEN for one CLI command at a time instead (Deploying unattended).

After authorization, run the deploy_command action's returned command_npx, or command_npx_windows on Windows, once as given. If npx cannot work, use its installed form where turnzero --version responds, following Ways to deploy.

Browser-login fallback #

Give the person these steps to run in their own terminal:

Run turnzero login if the CLI is already installed. Otherwise, install it first with the commands below:

npm install -g turnzero
turnzero login

On Windows, use turnzero.cmd instead of turnzero (Windows PowerShell).

  1. In the browser that opens, sign in if asked. If you prefer another browser, copy the address printed by turnzero login into it.
  2. Check the computer name and account, then choose Approve. If the account is wrong, choose Sign out, run turnzero login again, and sign in to the correct account. Use an emailed code if Google or GitHub keeps signing you back into the wrong account.
  3. Tell your AI assistant when the terminal prints authorized:. This output names the platform address, account, computer, and expiry.

For a remote computer or one without a browser, have the person run turnzero login --no-browser. They can open the printed address on any computer, approve access, and paste the page's code into the terminal. If they opened a normal login link on another computer, stop that login and restart with --no-browser: the normal callback expects a browser on the computer running the command.

If the browser cannot open or return its code, turnzero login waits for the code shown on the page.

Use turnzero whoami to check which account the CLI uses. Authorization lasts 30 days; turnzero login renews it. This authorization covers the whole account; for a token limited to one application, follow Mint a token, where the person runs token claim in their own terminal.

Local application setup can also work without login: turnzero provision --application <application id> with nothing piped prints an MCP call. The returned command writes local settings without authorizing the CLI. See Write the environment file.

Connect an unattended AI coding agent with a token #

An unattended MCP client can use a minted token instead of browser sign-in. Mint it from an existing signed-in connection and put the claimed value in the runner's secret store. Configure the client to send it as Authorization: Bearer <token> to https://turnzero.ai/mcp.

A token connection lists tzCloud tools only. A program that needs tzTrack or tzMesh uses that product's own server with its own token.

For Codex, make the stored value available as TURNZERO_CLOUD_MINTED_TOKEN in the environment that starts Codex. Add a separate connection with codex mcp add turnzero-unattended --url https://turnzero.ai/mcp --bearer-token-env-var TURNZERO_CLOUD_MINTED_TOKEN. The command stores the variable's name, not the token. Start a new chat and check the connection with start. If an application-scoped token gets token_scope_refused, call read_account instead; the token's existing limits still apply. See OpenAI's MCP configuration reference for other configuration options.

The token limits which applications and actions the client can use. An application-scoped token cannot create another application, and a minted token cannot mint another token. A run that creates an application needs an account-scoped token; the token's grants must allow each action the run needs. Deploy with nobody at the keyboard covers the CLI credential and deployment steps.

Refusals #

If connecting or signing in fails, the refusal's name gives the cause. The table below gives the common causes and remedies. The refusals reference lists every platform refusal, and Identities and passkeys covers passkey failures.

On the MCP endpoint, a refusal appears in an OAuth challenge's WWW-Authenticate header or a response body. During sign-in, it can appear on the page or in the redirect back to the AI assistant.

Refusal Status Cause Remedy
authentication_required 401 The connection presented no credential, or one that resolves to no account: expired, signed out. The detail says whether one was presented and names the scope to sign in again under, tzcloud. In Claude Code, type /mcp, choose turnzero, and sign in. In Codex, run codex mcp login turnzero. This sign-in does not authorize the turnzero command; use the authorization steps above when your chosen deployment method needs it.
invalid_token 401 The credential cannot sign in to this service, for example an expired or revoked access token. Let your AI assistant renew or sign in again. Do not edit tokens by hand.
account_suspended 403 Your account is suspended, so the sign-in also fails. Ask platform staff to reinstate the account; nothing on your side clears it.
app_credential_not_admitted 401 The credential is an application's platform credential, which cannot connect to the MCP server. Connect under your own sign-in or a minted token.
transfer_grant_not_admitted 401 The credential is a storage transfer grant, which works only on the storage file routes. Connect under your own sign-in or a minted token.
secret_grant_not_admitted 401 The credential is a secret grant, which works only for its one secret write or a local run's setup. That setup replaces the platform credential, and the database credential if the manifest declares a database. Connect under your own sign-in or a minted token.
retired_host 421 The configured URL uses a hostname the platform retired. The detail gives the current address. Use the address in your tool's setup steps above.
context_changed 409 The stamp your AI assistant sent does not match the text it read. The catalog or content changed while your AI assistant read it in parts, or the stamp came from another read, such as a page's stamp sent with section. Ask your AI to restart the read at offset zero without a stamp.
sign_in_failed 400 The provider sign-in could not be verified. Start over from the AI assistant.
access_denied 302 You declined at the identity provider, or chose Cancel on the page that asks you to allow an AI assistant. Your client receives error=access_denied. Start the sign-in again, accept at the provider, and choose Allow access.
unrecognized_invitation 403 No valid invitation for this address: none, one for another address, or one that is used, expired, or revoked. Open the invitation URL issued to your address and sign in with a sign-in method that verifies that address. If it is used up, ask for a new one.
realm_creation_ceiling 403 The platform's limit on new accounts is reached, so sign-ups are paused. The sign-in page says so instead of showing the refusal's name. Try again later, or use an invitation: its link still creates an account while sign-ups are paused.
cloud_required 403 The platform refused the call's Turn Zero Cloud access check. Every account includes Turn Zero Cloud. Call read_account to confirm the account, then repeat the request.
address_held_by_another_account 409 The address this sign-in method verified belongs to a different account; nothing is linked or merged. Sign in with the sign-in method that account already uses.
signin_code_invalid 400 The sign-in code is wrong, expired, replaced, or from another browser. The sixth wrong attempt ends the code. Type the code from the latest message, in the browser that asked for it, or choose Request a new code.
signin_code_rate_limited 429 Too many codes were sent to this address, or too many attempts failed within the hour, or the platform's sending limit was reached. Wait for the hour to pass, or sign in with another method.
signin_rate_limited 429 Too many emailed-code sign-ins started from your network. An IPv6 address counts as its whole /64 network. Wait, then start the sign-in again.
email_domain_undeliverable 400 An emailed-code start was for an address whose domain publishes no mail server, so no code could reach it. Correct a typo in the address and start again. Where you entered no address, as when a code goes to the address an existing account uses, sign in with another method.
invalid_client 401 The AI assistant's client registration is no longer on file, for example after a long time unused. In the browser, the sign-in shows a page titled Connect your tool again. Remove this server's sign-in in your AI assistant and connect again; the AI assistant registers itself again.
invalid_grant 400 The code or refresh token is unknown, expired, already used, or from a session that ended. A passkey offer ended by a sign out everywhere is also refused this way. Sign in again through the host. To add a passkey, sign in again and use the site's passkey page.