--- title: Quick start description: Connect tzTrack in one step, from Claude Code, Codex, Claude, ChatGPT, or another AI tool, or from a script or a CI job with no AI tool through the REST API. slug: /getting-started/quick-start order: 0 visibility: public redirects_from: [] --- # Quick start This page connects Turn Zero Track (tzTrack), your AI's issue list, to your AI tool. Pick the line for your tool, run it, and sign in once in your browser with your Turn Zero account. A script or a CI job with no AI tool uses the REST API instead, after the AI tools below. ## Connect an AI tool ### Claude Code Run this in a terminal: ```text claude mcp add --transport http tztrack https://tztrack.ai/mcp ``` Then type `/mcp` in Claude Code, choose `tztrack`, and finish the sign-in in your browser. To add tzTrack for every folder, put `--scope user` before `--transport`. ### Codex Run this in a terminal: ```text codex mcp add tztrack --url https://tztrack.ai/mcp ``` Your browser opens for the sign-in. Where it does not, run `codex mcp login tztrack`. ### Claude or ChatGPT In Claude, the desktop app or claude.ai, open **Settings**, then **Connectors**, and choose **Add custom connector**. Enter `tztrack` as the name and `https://tztrack.ai/mcp` as the URL, then choose **Continue**. Keep **Sign in now**, choose **Register automatically** under **OAuth client**, and choose **Add**. In a chat, turn `tztrack` on from the **+** menu, under **Connectors**. In ChatGPT, turn developer mode on in its settings, where your plan offers it. Add a custom connector with the address `https://tztrack.ai/mcp`, then turn it on in each chat where you want it. ### Another AI tool A tool that takes an MCP server by its address takes the same one, `https://tztrack.ai/mcp`, usually as a custom connector. It opens the Turn Zero sign-in in your browser. ### Sign in and check Sign in with your Turn Zero account. Then ask your AI: *"Find my open issues in tzTrack."* It lists the open issues of your space, or says the space holds none yet. If your account holds no space yet, your AI asks you whether to make one. [Connect your AI tool](/getting-started/connect-your-ai-tool) explains each step, and [Name your space in a setting file](/getting-started/name-your-space-in-a-setting-file) makes every session of a project use the same space. ## Connect a script with no AI tool A script or a CI job works your space through the [REST API](/reference/rest-api). It needs a tzTrack token first. Get one either way below, then keep it as `TZTRACK_TOKEN` in the script's secret store, never in a file you commit. ### 1. Get a token The quickest way is to ask your AI tool, signed in to Turn Zero Cloud, to mint one. It calls `mint_token` with the grant `tztrack` and a label that names the script. It gives you a `token claim` line to run in a terminal of your own, so the token never passes through the chat. [Mint a token](https://turnzero.ai/cloud/guides/mint-a-token/) gives the steps. A script can instead sign in by itself with a code, which you allow in a browser. Register the script as a sign-in client once, and keep the `client_id` it answers: ```text curl -s -X POST https://turnzero.ai/oauth/register -H 'content-type: application/json' -d '{"grant_types":["urn:ietf:params:oauth:grant-type:device_code"],"client_name":"My script"}' ``` Ask for a code, naming tzTrack's address as the `resource`: ```text curl -s -X POST https://turnzero.ai/oauth/device_authorization -d client_id= -d resource=https://tztrack.ai/mcp ``` The answer carries `user_code`, `verification_uri_complete`, and `device_code`. Open the link in any browser, sign in, check the code, and choose **Allow**. The code lasts ten minutes. Meanwhile the script polls every five seconds with the `device_code`: ```text curl -s -X POST https://turnzero.ai/oauth/token -d grant_type=urn:ietf:params:oauth:grant-type:device_code -d client_id= -d device_code= ``` It answers `authorization_pending` until you allow it. The next poll then answers `access_token` once. If your account does not hold tzTrack, the poll answers `invalid_grant` and no token is made. [Sign in from a script](https://turnzero.ai/cloud/guides/sign-in-from-a-script/) gives every answer the poll can give. ### 2. Make a call Every call is a `POST` to `https://tztrack.turnzero.ai/v1/`, with the token in the `authorization` header and one JSON object as the body. This lists the open issues of your space: ```text curl -s -X POST https://tztrack.turnzero.ai/v1/list -H "authorization: Bearer $TZTRACK_TOKEN" -H "content-type: application/json" -d '{"state": "open", "limit": 20}' ``` Where your account holds several spaces, name one with `space` in the body. The answer holds the space's id as `space`, the act as `act`, and the page of issues as `result`. ### 3. Raise an issue This raises one issue, as a CI job might after a failed run: ```text curl -s -X POST https://tztrack.turnzero.ai/v1/submit -H "authorization: Bearer $TZTRACK_TOKEN" -H "content-type: application/json" -d '{"origin": "test", "kind": "bug", "title": "The nightly build fails on the login test", "key": "nightly-login-test"}' ``` The `key` is your own: repeat the call with the same key and the issue is raised once. A refused call answers `error` and `detail` and changes nothing. [Refusals](/reference/refusals) gives each one's remedy. ## Give this page to your AI This page's Markdown copy is at its address followed by `index.md`: `https://turnzero.ai/tztrack/getting-started/quick-start/index.md`. A tool that can read this manual can fetch it and follow it. [The home page](/) says who can read this manual. ## Related - [Connect your AI tool](/getting-started/connect-your-ai-tool) explains the sign-in and checks the connection. - [Name your space in a setting file](/getting-started/name-your-space-in-a-setting-file) makes every session of a project use one space. - [REST API](/reference/rest-api) lists every act with its level, request, and answer. - [Refusals](/reference/refusals) lists every refusal with its cause and remedy.