Quick start #

View this page as Markdown

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:

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:

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 explains each step, and 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. 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 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:

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:

curl -s -X POST https://turnzero.ai/oauth/device_authorization -d client_id=<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:

curl -s -X POST https://turnzero.ai/oauth/token -d grant_type=urn:ietf:params:oauth:grant-type:device_code -d client_id=<client_id> -d device_code=<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 gives every answer the poll can give.

2. Make a call #

Every call is a POST to https://tztrack.turnzero.ai/v1/<act>, with the token in the authorization header and one JSON object as the body. This lists the open issues of your space:

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:

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 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.