Back to overview

Connect Claude Code

I want to …

… let Claude Code read and change this workspace's tasks, so you can start on a task from your terminal and hand it to testing when you are done.

Before you start

  • You need an API key of this workspace, see "Create and revoke API keys". Pick only the boards Claude Code needs.
  • The key's permissions decide what Claude Code may do. Read only reads. Read and write also creates and changes tasks, fills in testing, and comments. Deleting tasks needs Full access.
  • API keys need the Ultra plan of the Owner or Admin who creates them, and they are in beta.
  • Tasks, comments, and bugs are written by people in your workspace. A task could contain instructions aimed at an AI. Give the key as few boards and permissions as it needs, and check what Claude Code is about to do.

Here's how

  1. Create a key and copy it. For the hand-off to testing, pick Read and write.
  2. Put the key into the environment variable ZEITLICHT_API_KEY, for example with export ZEITLICHT_API_KEY=zlk_… in your shell profile, or through your password manager's command line. Never write the key into a file of your repository.
  3. To connect one project, create the file .mcp.json in its root folder with this content: {"mcpServers": {"zeitlicht": {"type": "http", "url": "https://start.zeitlicht.app/api/mcp", "headers": {"Authorization": "Bearer ${ZEITLICHT_API_KEY}"}}}}. The file holds only the name of the variable, not the key. You can commit it, and everyone on the team uses their own key.
  4. To connect all your projects instead, run claude mcp add --transport http --scope user zeitlicht https://start.zeitlicht.app/api/mcp --header "Authorization: Bearer $ZEITLICHT_API_KEY" in the terminal. Claude Code then keeps the key in its settings on your computer.
  5. Start Claude Code in the project. With .mcp.json, Claude Code asks once whether to use the server. Agree. /mcp lists zeitlicht as connected.
  6. Ask in your own words, for example "Which Zeitlicht tasks are assigned to me?" or "What does task 3f2a9c1e need?". Claude Code picks the tools itself, such as search_tasks and get_task. You can name a task by its ID, its short ID, or its link. Before a tool that changes something, Claude Code asks for your OK.
  7. To start on a task, type /mcp__zeitlicht__start_task followed by the task's short ID or link. Claude Code loads the task, sums it up, and suggests a branch name such as 3f2a9c1e-login-fix. Put the short ID in commit messages and pull request titles, so they can be matched to the task later.
  8. When the work is done, type /mcp__zeitlicht__handoff_to_testing followed by the short ID, and if you like the testers' emails separated by commas and the ID of a column such as Test. Claude Code writes test instructions from your changes and calls request_testing: testing switches on, the instructions appear in the task, the testers are added and get a notice in their activity, and the task moves to that column.

The result

Claude Code reads the tasks on the boards the key allows and, with write permissions, creates and changes them, fills in testing, reports bugs, and comments, as you. Every request shows up in the key's access log.

Common questions

Which tools does Claude Code get?

With every key: whoami, list_boards, get_board, list_members, list_tags, list_topics, search_tasks, get_task, get_task_history, list_comments, and list_bugs. With Read and write also create_task, update_task, move_task, add_checklist_items, update_checklist_item, remove_checklist_item, create_tag, create_topic, add_web_link, remove_web_link, request_testing, update_testing, disable_testing, set_my_verdict, report_bug, update_bug_status, add_comment, and delete_comment. delete_task needs Full access. Claude Code only sees the tools the key allows. create_tag and create_topic also need a key for all boards; a key for selected boards gets all-boards-required, and list_members shows it no email addresses.

Who is named when Claude Code changes a task?

You, the person who created the key, with the key's name next to it. Comments and bugs are written in your name too. Claude Code can edit and delete only comments written that way or by you.

/mcp shows zeitlicht as failed. What now?

Usually the key is wrong, expired, or revoked, or ZEITLICHT_API_KEY is not set in the terminal that started Claude Code. Look up the key under API keys. In the terminal, curl -H "Authorization: Bearer $ZEITLICHT_API_KEY" https://start.zeitlicht.app/api/v1/me shows the key's workspace, or why it is refused.

Does this work in Claude Desktop or on claude.ai?

Not yet. They connect without your key in a header and need a sign-in, which comes in a later version.

Can Claude Code see other workspaces?

No. A key belongs to one workspace and sees only the boards picked for it. For a second workspace, create a key there and add a second server under another name, such as zeitlicht-team.

Related topics