What your agent can do with a Zeitlines plan

Why the plan needs to be readable in the first place

An agent working in your codebase already has the code, the tickets and the conventions. What it does not have is the intent: what is planned next, in which order, what depends on what, and what has been promised to somebody outside. That knowledge sits in slide decks, whiteboards and people’s heads.

Giving an agent an API onto a picture does not help. What helps is the plan existing as records with fields: a phase is a phase, a dependency is a dependency, a status is a status. Then an agent can query it and act on it.

The tools

Timelines and their contents, plus the pricing model that the product-roadmap plugin contributes.

Tool	What it does
list_timelines	Every database timeline, with id, name and description
list_users	The linkable users, for the owner field on an item
get_timeline	One timeline in full: items and groups
add_item	Appends an item; needs at least a start and a label
update_item	Patches an item, only the fields given; metadata is merged
delete_item	Removes an item by id
add_group / update_group / delete_group	The lanes items sit in
replace_timeline	Replaces a whole timeline at once
set_pricing	Replaces the pricing model wholesale, and enables the plugin
add_feature / update_feature / delete_feature / move_feature	A single pricing feature, and its order
add_tier / update_tier / delete_tier	A single pricing tier
set_tier_value	One cell of the tier × feature matrix
add_highlight / update_highlight / delete_highlight	One card tile
set_versions	Replaces the ordered version list

dependsOn and owner live under an item’s metadata. An owner carries the e-mail of a user from list_users; a free-text name is stored but renders unlinked.

Connecting Claude Code

Register the server once, from a checkout of the Zeitlines repository, and it is available from any directory:

claude mcp add -s user timelines -- \
  <repo>/node_modules/.bin/tsx <repo>/scripts/mcp/server.ts

Two variables configure it, both read server-side:

Variable	Meaning
TIMELINES_LIVE_URL	The deployment to work against. Required, no default; the server aborts with a clear message if it is missing.
MCP_API_TOKEN	The service token. Must match the variable of the same name on the deployment, or the request is answered by the login gate instead.

What it does not do

• It does not touch file-based timelines. Those are read-only on a deployment, so they are not exposed for editing at all.
• It does not keep a local copy. Every call goes to the live deployment. There is deliberately no cached snapshot, because a stale plan is indistinguishable from a current one and gets trusted as if it were.
• It does not carry domain rules. An agent can move a date; it cannot yet be told to recompute a statutory deadline, because plugins cannot contribute tools of their own today. That seam is open work, and until it exists a plugin extends the data model but not the agent’s vocabulary.

Where to go next

• A worked example: keeping a roadmap current from Claude Code.
• Self-hosting: what a deployment needs before an agent can reach it.
• The MCP chapter in the repository : the authoritative reference for these tools.

Frequently asked questions

Can an AI agent edit a Zeitlines roadmap?

Yes. Zeitlines ships an MCP server over stdio. Claude Code can list timelines, read one in full, add, update and delete items and groups, replace a timeline wholesale, and maintain the pricing model contributed by the product-roadmap plugin.

Which timelines can an agent change?

Only database-backed ones. File-based timelines are read-only on a deployment, so the server does not offer them for editing rather than failing halfway through a write.

Does the agent work against my live deployment?

Yes, always. TIMELINES_LIVE_URL is required and has no default: every read and write goes through the deployment’s API to the database, so the database stays the single source of truth and a change is live when the tool call returns. The server aborts with a clear message if the variable is missing.

How are agent edits attributed?

Writes made through the MCP server are recorded as mcp in the row’s updated_by, so a change made by an agent is distinguishable from one made by a person in the browser.

Do agent edits conflict with people editing at the same time?

They go through the same optimistic locking. Every write carries the row version it was based on, so a stale write is rejected rather than silently overwriting somebody else’s change, whether it came from a browser or an agent.

Does an agent need a login?

It uses a service token rather than a Google sign-in. The server sends X-MCP-Token on every request and the deployment’s edge function compares it in constant time. If the token is unset the bypass is inactive and the site stays gated behind the login for everyone, including agents.