Connect your tool

Prompt:

Connect this project to Turn Zero Cloud so you can deploy it from here.

Also works:

  • "Set up the Turn Zero Cloud connection and sign me in."
  • "Add Turn Zero Cloud to this project's tools."
  • "What can Turn Zero Cloud do for this project?"
  • "My sign-in code never arrived."
  • "How do I sign out on every device?"

What your tool does

  • In Claude Code, runs claude mcp add --transport http turnzero-cloud https://turnzero.ai/mcp. If you keep the configuration in the project, it writes the turnzero-cloud entry into your project's .mcp.json instead.
  • In Codex, runs codex mcp add turnzero-cloud --url https://turnzero.ai/mcp and then codex mcp login turnzero-cloud, and asks you to finish the sign-in the login opens in your browser.
  • In the Claude desktop app or claude.ai, adds no connector itself. You add it under Settings, then Connectors, as step 2 describes, and the tool works through it once it exists.
  • Signs in at the connector's first request. If the connection has not signed in, the server answers that request, before any tool call, with a sign-in challenge, and Claude Code and Codex open the sign-in page in your browser. You sign in there, and the tool connects again.
  • Calls list_context and reads the overview entry with read_context. Both describe the capabilities, the contracts, and what each action needs first.
  • Calls read_account, and reports the connection as verified when it returns your account's identities and standing rather than a request to sign in.
  • Reads this documentation through read_documentation with the tree cloud, the index first, when it needs a page, or searches it with a few words in query, which needs no tree.
  • Writes nothing else into your project, changes nothing on your account, and asks for no approval, because every action on this page only reads.

What you need

  • One of the supported AI tools on your computer: Claude Code, the Claude desktop app, claude.ai, or Codex desktop or CLI. See What your computer needs.
  • A web browser for signing in.
  • While Turn Zero Cloud is in private beta, an invitation sent to your email address. Signing in without one will not create an account.

Before your AI starts

This section is for your AI tool: what it checks and gathers before it begins. You don't need to do these steps yourself.

  • Nothing beyond the tool itself. This guide makes the connection, so no earlier connection or sign-in is needed.

Steps

Turn Zero Cloud joins your AI tool as a Model Context Protocol (MCP) server. Once connected, your assistant can read the platform's contracts, act on your account, and deploy an application you have built. The service is hosted remotely, so connecting installs no local server.

The server calls itself turnzero-cloud, and every example here uses that name. Your tool keeps it as a local label, so another name also works. The name is the prefix you will see on the server's tools in your assistant, which is the only reason to prefer this one.

1. Claude Code

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

Or add it to your project's .mcp.json:

{
  "mcpServers": {
    "turnzero-cloud": {
      "type": "http",
      "url": "https://turnzero.ai/mcp"
    }
  }
}

2. Claude desktop app and claude.ai

The Claude desktop app and claude.ai on the web share one list of connectors, kept with your Claude account. A connector you add in one place appears in the other.

  1. Open Settings, then Connectors. On claude.ai the same list is under Customize, then Connectors. On a Team or Enterprise plan, an owner adds the connector under Organization settings, then Connectors, and each member then chooses Connect beside it.
  2. Choose Add custom connector.
  3. Enter turnzero-cloud as the name and https://turnzero.ai/mcp as the MCP server URL, then choose Continue.
  4. Claude checks the URL and shows the authentication settings it found. For this server it fills in Sign in now under Authentication; keep that setting. Under OAuth client, choose Register automatically. Leave Request headers empty.
  5. Choose Add. Your browser opens the Turn Zero sign-in page. Sign in with the sign-in method your invitation specified, then return to the app. The connector now shows as connected.
  6. In a conversation, open the + menu, choose Connectors, and turn turnzero-cloud on if it is off.

The three Authentication settings differ by one word, so keep the one Claude fills in:

  • Sign in now signs you in while the connector is added.
  • Sign in when needed asks for a sign-in the first time the server needs one. This server needs one from its first request, so this setting asks as soon as the connector first connects. It asks through an in-conversation prompt that Anthropic describes as experimental.
  • No sign-in never signs in. The server answers every request from a connection that has not signed in with a request to sign in, so the connector reaches none of the server's tools.

Claude does not let you change a connector's authentication settings after it is added. To repair a connector added with another setting, remove it under Settings, then Connectors, and add it again keeping Sign in now.

Your app may show the name, the URL, and Advanced settings on one screen. That is the earlier version of the dialog, which offers no authentication choice. Leave Advanced settings empty and choose Add. A connector that has not signed in reaches none of the server's tools. If your app offers to connect or sign in, choose it and finish the Turn Zero sign-in in your browser. Otherwise remove the connector and add it again once your app shows the two-step dialog, keeping Sign in now, or connect through Claude Code or Codex instead.

3. Codex desktop and CLI

Run these three commands in a terminal. No test checks this sample.

codex mcp add turnzero-cloud --url https://turnzero.ai/mcp
codex mcp login turnzero-cloud
codex mcp list

Finish the browser sign-in, then open a new task. The desktop app and the CLI read the configuration in the selected Codex home. If your client offers a registration choice, use dynamic client registration (DCR). The explicit command is codex mcp login turnzero-cloud --oauth-client-registration dcr.

4. Sign in

Your tool signs in before it reads anything through the connection: the server answers every request from a connection that has not signed in with a request to sign in. The Claude app asks you to sign in while you add the connector, under the Sign in now setting from step 2. In Claude Code and Codex, the tool opens the Turn Zero sign-in page in your browser the first time it connects.

Sign in with the route your invitation specified. The page shows the provider buttons first, Continue with GitHub and then Continue with Google. An address form follows, whose button reads "Continue with email". Where you hold a passkey, the address field offers it as you focus the field. Inside the form, after its button, the link "Use a passkey instead" signs you in with a passkey on a security key or another device. There is no password to create.

To sign in with an emailed code, enter your address and choose Continue with email. The message comes from donotreply@turnzero.ai with the subject "Your Turn Zero sign-in code", and contains a six-digit code and no link. Type the code on the page that asked for it, in the same browser, within ten minutes. Read your mailbox in another tab or on another device.

The limits on codes:

  • A code allows five attempts. A sixth try is refused and ends the code.
  • Send a new code on the code page sends a fresh code to the same address and replaces the old one. Use it when a code has not arrived after a few minutes.
  • An address receives at most five codes an hour.
  • Ten wrong entries for one address in an hour stop further codes to it until the hour passes. Google and GitHub still work.
  • While an account needs an invitation, a code goes only to an address that already has an account, or to the address on the invitation you opened. Open the invitation first, then enter its address. The page looks the same whether or not a message was sent.

While the platform is in private beta, a first sign-in creates the account only if your address has an invitation; otherwise the page says so and creates nothing. After you sign in by emailed code, the platform offers to register a passkey, which then signs you in without waiting for a code. A Google or GitHub sign-in offers none. A later sign-in you make to approve a waiting request goes straight to the request, and the offer waits for your next sign-in by code. Once sign-ups open, the page your tool opened also offers Create an account.

After you sign in, the connection acts with your account's identity and permissions. The tool renews its tokens without asking you to sign in again, but an expired or revoked credential can require a new sign-in. Sign-in, sessions, and tokens describes the tokens the connection uses and what ends it.

5. Verify the connection

Ask the connected assistant to call list_context, read overview with read_context, and then call read_account. The account read confirms that your connection is signed in.

If the browser finishes but the client stays disconnected, return to the host and retry its login once. Use the exact /mcp URL above. Do not paste bearer tokens or browser callback URLs into the configuration.

6. Read the context

Ask your tool to read the context the server provides before it chooses actions. It describes the available capabilities, the contracts, and what each action needs first. A client that supports only tools calls list_context and passes the returned IDs to read_context. The catalog includes the overview, the contracts, the manifest schema, the guides, and the available skills.

Ask your tool to read this documentation's index with read_documentation first, then the pages it needs. read_documentation takes the tree cloud for every account, and blueprint and tzdocs for an account with Turn Zero Blueprint access. A search with query needs no tree: it reads every tree your account can read. The generated reference for read_documentation and read_context lists their options and how to read a long text in parts.

The server offers tools, resources, and prompts. There is one tool per management action your tool may call, and the prompts are the platform's skills. A tool's description in the tool list says what to know before the call. Where a description names a page of the action reference, that page holds the rest, and read_documentation reads it by its route as page. MCP resources and prompts lists the resources and the skills.

A tool call that sends a member its action does not take is refused invalid_request, and the refusal names the members the action takes.

The text the server sends your tool when it connects opens by saying what Turn Zero Cloud is for and telling the tool to read the overview first.

7. Refresh or remove the connection

Turn Zero Cloud upgrades happen on the server, and a routine upgrade keeps your sign-in and the connection's tokens. After an update, refresh the connection's tool list or start a new task:

  • In Claude Code, use /mcp to inspect or authenticate.
  • In Codex, run codex mcp login turnzero-cloud again if authentication needs repair.
  • In the Claude app, Settings, then Connectors lists the connector and offers Remove. To change its sign-in setting, remove it and add it again.

To remove a connection, use claude mcp remove turnzero-cloud, or codex mcp logout turnzero-cloud followed by codex mcp remove turnzero-cloud, or Remove under Settings, then Connectors in the Claude app. Removing it disconnects the host. It does not delete your Turn Zero Cloud account or applications, and it does not sign you out on your other devices. Sign out on the site ends that browser's session alone. Sign out everywhere on the Sign-in & security page, or the sign_out_everywhere action, ends every session of the account at once, on every device (What ends a connection).

Expected result

In Claude Code, /mcp lists turnzero-cloud as connected, and the server's tools appear in your assistant with that name as their prefix. In Codex, a new task can call the server's tools, and read_account returns your account. In the Claude app, the connector shows as connected under Settings, then Connectors, and is on in the conversation's Connectors menu.

list_context returns the catalog, and read_context returns the overview text. read_account returns your account rather than a request to sign in: each identity (a provider and the subject it verified), the account's standing, the provider-verified address, and the connection's grants.

Refusals

On the MCP endpoint, a refusal arrives either as a standard OAuth challenge, with the error in the WWW-Authenticate header, or as a response that gives the refusal's name. On the sign-in page, a refusal is shown on the page or returned to your client on its redirect. The rows below are the refusals you can meet while connecting, signing in, and registering a passkey.

Refusal Status Cause Remedy
authentication_required 401 The connection presented no credential, or one that matched no account. The detail says which. Finish the sign-in your tool opens. In Codex, run codex mcp login turnzero-cloud.
invalid_token 401 The credential cannot sign in to this service, for example an expired or revoked access token. Let your tool renew or sign in again. Do not edit tokens by hand.
insufficient_scope 403 The access token is valid but lacks the scope the call needs. Sign in again through the host.
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.
end_user_credential_not_admitted 401 The credential is an end-user session token, which works only on its application's realm. 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 write of one secret, or for a local run's two re-mints. 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 https://turnzero.ai/mcp, the URL on this page.
misdirected_origin 421 The request did not come through the platform's public address. Connect to https://turnzero.ai/mcp and no other address.
not_yet_provisioned 501 The tool called a catalog action that no build serves. Check the action's page in Management actions and choose one the platform serves.
context_not_found 404 The content ID given to read_context is not in the catalog. Take the ID from list_context; an ID is neither a file path nor a URL.
context_changed 409 The catalog or content changed while your tool was reading it in parts. Restart the read at offset zero without a stamp.
context_unavailable 503 A source or a documentation tree is not available. Retry later; nothing on your side clears it.
sign_in_required 401 No sign-in method is set up for the request, or a passkey page was opened without a signed-in browser. Sign in first. For the passkey pages, sign in on the site, then open them.
sign_in_failed 400 The provider sign-in could not be verified. Start over from the tool.
access_denied 302 You declined at the identity provider. Your client receives error=access_denied. Start the sign-in again and accept at the provider.
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 route that verifies it. 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. Once sign-ups open, the 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.
address_held_by_another_account 409 The address this route verified belongs to a different account; nothing is linked or merged. Sign in with the route that account already uses.
identity_already_bound 409 The provider identity you tried to link already belongs to a different account. Sign in to that account, or link a different identity.
continue_new_removed 410 You used a retired route that created a second account for an address another account already has. Link the identity to the existing account; the sign-in page offers that choice.
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 Send 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 route.
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 route.
rate_capped 429 Your network sent too many client registrations in the hour or requests in the minute. An IPv6 address counts as its whole /64 network. Wait for the window to pass before you retry.
invalid_client_metadata 400 The client's registration had no usable redirect_uris. Update the client; the host registers itself, and nothing needs setting by hand.
request_too_large 413 The client's registration is larger than 16 KiB. Update the client.
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.
invalid_scope 400 The requested OAuth scope is unknown, malformed, or broader than the one granted. Let the host request its standard scope, or update the client.
invalid_target 400 The client sent a different server address from the one it signed in to. Use the exact https://turnzero.ai/mcp URL; remove and re-add a connection that uses another.
invalid_request 400 Input is missing or malformed. The detail gives the field. Any input containing a NUL character (U+0000) or an unpaired UTF-16 surrogate is refused too, and its detail gives the character rather than a member. Correct the field, usually by updating the client or adding the connection again. Remove a character the detail mentions.
passkeys_not_configured 404 The platform offers no passkey route, because its passkey host or the sender of the emailed codes is not set up. Sign in with another route.
passkey_requires_email 409 A passkey registration was asked for an account that does not sign in by emailed code. A passkey is a faster way to sign in by code. Sign in by code once at the address your Google or GitHub sign-in verified, which adds the code to your account. Then register the passkey at that sign-in's offer or from the site's passkey page.
offer_cookie_required 400 The passkey offer was opened without the cookie the offer page set, or that browser signed out, which clears the cookie. Return to the offer page before the offer lapses, or register the passkey later from the site's passkey page.
passkey_registration_refused 400 The passkey registration did not verify. Register again from the site's passkey page.
passkey_already_registered 409 This passkey is already registered. Use the registered passkey, or register a different authenticator.
passkey_challenge_unknown 400 The passkey challenge is unknown, expired, or was issued for another purpose. Start the passkey steps again from the page.
passkey_origin_mismatch 400 The passkey steps ran on a site other than the platform's. Run them from the sign-in page at https://turnzero.ai.
passkey_rp_id_mismatch 400 The authenticator reports a site other than the platform's. Run the passkey steps from the sign-in page at https://turnzero.ai.
passkey_assertion_refused 400 or 401 The passkey response could not be read (400), or its signature or user failed to verify (401). Try the passkey again, or sign in with another route and register it again.
passkey_counter_regressed 403 The authenticator's use count went backwards, which can mean a copied authenticator. Sign in with another route, remove the passkey from the site's passkey page, and register it again.
passkey_unknown 404 No passkey matches, or its account no longer exists. A passkey on an account that does not sign in by emailed code is removed and refused this way. Sign in with another route. To register a passkey again, sign in by emailed code and accept the offer.
passkey_not_stranded 409 You asked for the special removal of a passkey that still works on this site. Remove it the ordinary way, after using it once.
internal 500 An unexpected error. The detail is one fixed sentence that includes a reference. Retry. If it persists, report it and quote the reference.