API and integrations
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 onlyreads.Read and writealso creates and changes tasks, fills in testing, and comments. Deleting tasks needsFull access. - API keys need the Ultra plan of the
OwnerorAdminwho 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
- Create a key and copy it. For the hand-off to testing, pick
Read and write. - Put the key into the environment variable
ZEITLICHT_API_KEY, for example withexport 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. - To connect one project, create the file
.mcp.jsonin 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. - 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. - Start Claude Code in the project. With
.mcp.json, Claude Code asks once whether to use the server. Agree./mcplistszeitlichtas connected. - 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_tasksandget_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. - To start on a task, type
/mcp__zeitlicht__start_taskfollowed by the task's short ID or link. Claude Code loads the task, sums it up, and suggests a branch name such as3f2a9c1e-login-fix. Put the short ID in commit messages and pull request titles, so they can be matched to the task later. - When the work is done, type
/mcp__zeitlicht__handoff_to_testingfollowed 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 callsrequest_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.