# Tokens, CI and scripts

A personal access token connects clients that cannot open a browser, and lets CI and scripts read your workspace. How to make one, where it goes, and how to end it.

URL: https://docs.qaldy.com/mcp/tokens/

Use **Sign in with Qaldy** whenever the client can open a browser. Use a **personal access token** for CI, scripts and clients that cannot.

## Make one

In the console open **Agents** ([https://app.qaldy.com/agents](https://app.qaldy.com/agents)), or open the command palette and type "Connect an agent", then choose **Access token**. Pick **read-only** or **read and write**. The page puts the token into the snippet for your client, shows it once, and lists your tokens with when each was last used and a **Revoke** button.

Tokens made there expire in **30 days**. You can also make one under Backend, then Keys. From a terminal, `qaldy tokens create --name "GitHub Actions" --read-only --days 90` asks you to approve it in the browser and prints the token once. A token can never make another token.

A token:

- works in **one workspace** (the one it was made in), as **one person**, and never exceeds what that person may do;
- carries a **read** or a **write** scope. A read token is offered the read tools only;
- starts with `qat_`, is shown once, and is stored only as a keyed hash;
- is refused on anything that changes who has access, spends money or widens an app's reach (`console_only`, `approval_needs_console`).

## Put it in a client

Claude Code:

```sh
claude mcp add --transport http qaldy https://mcp.qaldy.com/mcp --header "Authorization: Bearer qat_…"
```

Cursor (`.cursor/mcp.json`):

```json
{
  "mcpServers": {
    "qaldy": {
      "url": "https://mcp.qaldy.com/mcp",
      "headers": { "Authorization": "Bearer qat_…" }
    }
  }
}
```

VS Code (`.vscode/mcp.json`); the token is asked for once and kept out of the file:

```json
{
  "inputs": [
    { "type": "promptString", "id": "qaldy-token", "description": "Qaldy personal access token", "password": true }
  ],
  "servers": {
    "qaldy": {
      "type": "http",
      "url": "https://mcp.qaldy.com/mcp",
      "headers": { "Authorization": "Bearer ${input:qaldy-token}" }
    }
  }
}
```

Anything that sends HTTP can call the REST API with the same header, on the routes marked with a token scope in the [API reference](https://docs.qaldy.com/reference/api/):

```sh
curl -H "Authorization: Bearer $QALDY_TOKEN" https://cloud-api.qaldy.com/v1/tokens/self
```

## In CI

Put the token in the job's secrets as `QALDY_TOKEN`. The [command line](https://docs.qaldy.com/cli/ci/) reads it, and the audit log records the call as `ci/…`. Make it read-only unless the job must build, and give it a short life.

## Ending access

Revoke a token on the Agents page, or from the machine that holds it: `qaldy logout` revokes the token the CLI is using. A revoked token stops working at once at the API. The MCP server remembers a successful check for ten seconds at most.

:::note Clients that only start local programs
Some desktop clients can only run a local command, not talk to a URL. A local server build for them exists in the repository; it is not distributed yet, so use one of the connectors above for now.
:::