KO hands your project data to an AI assistant: it reads reports, insights, journals and diagnostics and answers your questions in plain words, without opening the interface. That takes a key — you issue it yourself, and the screen puts it straight into a ready-made prompt for your agent.
Issue a key
- In your personal settings, open Connect AI.
- Press Add key…
- Name already says “Key of” and today’s date. It is better to write where the key will live: “laptop”, “team assistant”. The name is how you will know which key to revoke later.
- In Valid for, choose 30 days, 90 days, A year or No expiry — the last one is set if you change nothing.
- Optional: in Projects, tick the ones the key is limited to. Nothing ticked — the key sees every project you have access to. With many projects, use Find a project; Clear all drops the ticks.
- Press Issue.
A banner appears above the list: Key issued and already inside the prompt, with a Copy prompt button. The key itself is not shown as a separate line — it is already inside the prompt and inside the ready-made snippets in the How to connect block.
Take it right away: the key is shown once. KO stores only its fingerprint, so the screen cannot show it again. If you did not save the key, issue a new one and revoke the old one.
Connect an agent with the prompt
This is the main way, and it suits any agent that can edit files: Claude Code, Cursor, Copilot in agent mode.
- Press Copy prompt on the banner — or Copy on the Any AI agent card, the first one in the How to connect block.
- Paste the prompt into the agent’s chat.
The agent writes the config itself and checks the connection for you.
Claude Desktop and claude.ai do not accept a static key: their connector only supports signing in. That way of connecting is on the way — until then, a key does not help those two.
Set up by hand: Claude Code
The manual ways are folded under the prompt. Open Set up manually: Claude Code, VS Code and take the Claude Code card: one command with the key already in it.
- Press Copy.
- Paste the line into your terminal and run it.
The command registers the server at user level, so it appears in all of your projects at once, not only in the directory you happen to be in.
Set up by hand: VS Code
The VS Code card sits in the same place, under Set up manually: Claude Code, VS Code,
and gives you a .vscode/mcp.json file. The key is deliberately not inside it: the file
lives in your repository and would go to git with the first commit, so the editor asks for the
key itself and keeps it in its own secret store.
- Press Copy and put the file in your repository as
.vscode/mcp.json. - Open the file and press Start above the
koblock. - When the editor asks for the key, paste it. Right after issuing, the key sits on the card under the file, in the line “Your key — paste it when the editor asks”, with its own Copy button. This is the only place where the key is shown apart from the prompt.
If you need the server in every project rather than in one repository, run MCP: Open User
Configuration from the command palette and paste the same servers block there.
The server address, if you ever need it by hand, is written at the bottom of the How to connect block as Server address.
Verify
Ask the assistant to list your projects — it will call the ko_list_projects tool. A list of
projects instead of a refusal means the connection works.
On the KO side you see it in the Issued keys table: the Last call column shows a date instead of Never. The mark is written at most once a minute, so refresh the page after a minute rather than straight away.
What the assistant can read
The key opens eight tools, and every one of them only reads: the list of projects, a report, insights, the metric catalogue, the description of a report and of a project, a journal and diagnostics. There is no writing through the API — neither an assistant nor a program can change a setting or the data.
A key adds no rights, it only narrows them. It acts on your behalf and sees exactly what you see in KO: a project you were not given access to does not open through a key either. The Allowed column shows what the key may do; the tooltip holds the full permission keys.
Revoke a key you no longer need
In Issued keys, press ··· in the key’s row:
- Rename — when it is no longer clear whose key it is and where it runs.
- Revoke — the key stops working immediately, and everything connected with it stops receiving data. Revoking cannot be undone: you can only connect again with a new key.
A revoked or expired key disappears from the table: by default it shows only live keys. To see the rest, open the State filter in the block’s toolbar and turn on Revoked or Expired — each state shows how many keys it has. When no live key is left, the screen says No live keys, and Show all brings every key back into the table.
If it does not add up
- The assistant says it has no access. If the key is not in the table, it is no longer live. Turn on revoked and expired keys in the State filter: the key’s State column will say Revoked or Expired, and it will not work again — issue a new one.
YOUR_KO_API_KEYended up in the config. That is not a key but the place for one: this is how the examples look once the key can no longer be shown, and the banner above the cards says so. Paste yours, or issue a new key.- The assistant sees fewer projects than you expected. The key is limited to a list of projects — the Projects column shows how many, and the tooltip which ones.
- The KO tools never appeared in the agent. The config is written but the server is not
running: in VS Code it starts with Start above the
koblock, in other clients by restarting the session after the config changed. - Claude Desktop or claude.ai will not connect. That is not a fault: they do not accept a static key, and nothing on the KO side can work around it.
What is nearby
- Settings → Access — who sees the project and what they may do. A key inherits your rights, it does not extend them.
- How a report works — what exactly the assistant reads when it asks for a report.