# Use Taiga over MCP

Source: https://docs.tai.ga/start/mcp/

You can work with Taiga from the MCP client you already use:
Claude Code, Codex, VS Code, Cursor, Windsurf, Claude Desktop, Gemini CLI, Kiro, JetBrains AI Assistant, GitHub Copilot CLI or Zed.
The client connects through Taiga's MCP server and acts as you:
it can do what your role allows, and nothing more.

From your client you can ask where a product stands, what is waiting on you, why a run failed or how a product meets your policies,
and you can move work along: queue initiatives, review plans, and raise fixes for findings.

## Connect a client

In your account settings, open **MCP**. The page takes you through two steps.

1. **Create an access key.** Choose **Create key**, give the key a name, such as the computer it is for,
   and choose when it expires and its permissions (see below).
   Every permission is on to start with.
   The key appears on the page and is copied to your clipboard. Taiga shows it once.
   It stays on the page until you choose **I have saved it**, so copying the setup next does not lose it.
   If your browser does not allow the copy, copy it from the field; Taiga asks before you close it or leave the page without copying it.
2. **Add Taiga to your client.** Pick Claude Code, Codex, VS Code or **Other MCP clients**.
   - Claude Code and Codex: run the command in a terminal. It asks for your key; paste it and press Enter.
     Nothing appears as you paste, or asterisks in PowerShell, and the key stays out of your shell history.
     There is one command for macOS and Linux and one for Windows PowerShell; the page starts on the one for your computer.
   - VS Code: add the block to `.vscode/mcp.json`. VS Code asks for the key itself and keeps it in its secret storage.
   - Other MCP clients: add the block to your client's configuration. The page lists where each client keeps it,
     and the block already holds your key. Cursor also has **Add to Cursor**, which installs it in one click.

   Every setup runs the server with `npx`, so it needs Node.js 20 or later.
   Restart your client afterwards. Your key's row turns **Connected** once your client has used it.

You choose when a key expires: in 30 days, in 90 days (the default), in a year, or never.
A key that never expires keeps working until you revoke it, and its row says **Never expires**.
To stop a client using Taiga, revoke its key under **MCP**.

## Permissions

Taiga's tools come in five groups, and a key's permissions say which of them it offers:

| Permission             | What it covers                                                        |
| ---------------------- | --------------------------------------------------------------------- |
| **Where things stand** | Products, initiatives, runs, policies and findings                    |
| **Moving work**        | Queueing initiatives, reviewing plans, stopping runs, fixing findings |
| **Setup**              | Creating factories and products, linking repositories, importing code |
| **Observe**            | Deployments, monitoring, delivery metrics and packages                |
| **Documents**          | Writing and publishing documents and knowledge                        |

Turning one off keeps your client focused on the rest.
Turning one on never goes past your role: a client never gets an action your role does not allow.

To change a key's permissions, choose the sliders button on its row under **MCP**, then restart your client.

## What your client gets

- **Reads run, writes ask.** Every tool says, in its MCP annotations, whether it only reads,
  and its description says when it starts paid agent work or changes something other people see.
  A client that honours them can approve reads without asking and confirm the rest.
- **Workflows as prompts.** Start a session on a product, implement an initiative,
  or review a change against your policies, from your client's prompt menu. Claude Code shows them as slash commands.
- **Context as resources.** Your policies, a product's documents and its initiatives are resources you can attach to a conversation.

## How far Taiga goes on its own

With the **Setup** permission, your client can set how far Taiga goes by itself
when a sweep finds something in a product, for each kind of finding.
The kinds are: `vulnerable_dependency_exploited` (a vulnerability attackers are known to use),
`vulnerable_dependency_severe` (high or critical, not known to be used), `malware`,
`policy_violation`, `sast`, `iac_misconfig`, `secret` and `license`.

| Level     | What Taiga does                                                                      |
| --------- | ------------------------------------------------------------------------------------ |
| `notify`  | Raises no fix; the finding is yours to decide (`off` is the same)                    |
| `propose` | Plans a fix, and the plan waits for you                                              |
| `build`   | Plans and builds the fix, and the pull request waits for your review                 |
| `merge`   | Builds the fix and merges it once a re-scan confirms it, where auto-merge is allowed |

Each kind has a level Taiga goes no further than, and a level above it is refused.
The same tool sets how many fixes Taiga may raise on its own for the product per day (`dailyFixLimit`, 1 to 100).
A finding Taiga is not fixing on its own says why, in the findings list and on the finding itself:
it needs a major upgrade, the day's fixes are used up, Taiga has tried as often as it may, or it came back after a fix.
Reading a product tells your client what each kind resolves to and what decided it:
the product, the kind's starting level, the kind's own limit, or auto-merge being off above the product.

## Design standards tokens

Your [design standards](https://docs.tai.ga/context/design-system/) hold structured tokens (colours, spacing, type) beside their text.
Without a linked design-system repository, builds use those tokens, so your client can read and maintain them:

- `taiga_get_design_tokens` reads the tokens, from the draft or the published version, and says whether the text and tokens agree.
  It is among the tools for **Where things stand**.
- `taiga_update_design_tokens` edits existing tokens in the draft, up to 50 at a time.
  The edit is all or nothing: an unknown token or an invalid value refuses the whole edit, says what is wrong and leaves the draft unchanged.
  It is refused while a design job is running on the draft.
- `taiga_sync_design_tokens` has Taiga rewrite the draft's tokens to match its edited text, as the Studio's sync does.
  It returns a job; follow it with `taiga_get_design_token_sync`, which returns when the sync has finished or failed, or says it is still running so you can ask again.

Editing and syncing need the **Documents** permission, and both change only the draft.
Readers and builds keep the published version until you publish.
Each token edit is recorded in the audit log, with which tokens changed and not their values.

The draft says how its text and tokens stand with one of three statuses:

| Status                      | Meaning                                                        |
| --------------------------- | -------------------------------------------------------------- |
| `aligned`                   | The tokens were brought into line with the text as it is now   |
| `text_changed_after_tokens` | The text was edited after the tokens, so the two may disagree  |
| `unknown`                   | Taiga cannot tell, for example because the check itself failed |

Reading the design standards shows the status, and so does a section edit.
Publishing refuses a draft that is not `aligned`, and says how to fix it:
sync the tokens to the text, or edit them directly.
To publish anyway, ask your client to publish with `publishWithTokensOutOfLine`; the result then warns that the published text and tokens may disagree.

When the organization links a design-system repository, its tokens come from that repository, and these tools do not apply.

## What it asks you first

Some actions start paid agent work, such as queueing an initiative or raising a fix,
and some change things other people see.
Taiga marks those actions, and your client is told to ask you before it takes one.
Your client's own approval prompt is what enforces that, so keep it on for Taiga.

Text your client reads from Taiga, such as initiative descriptions and documents, was written by people or agents.
Your client is told to treat it as information, never as instructions.

## What stays in Taiga

Some things are done only in Taiga itself:
connecting GitHub, managing members and roles,
the Discovery conversation that specifies a new product,
and deleting factories and products.

## If it does not connect

- **The key still says Not used yet.** Restart your client after adding Taiga; most clients read their configuration only when they start.
  Check that `node -v` says 20 or later.
- **Your client says the key is missing, wrong or expired.** Create a new key under **MCP** and replace the old one in your client's setup.