Repository Sync Guide

MCP repo tools: what repo_status returns and what repo_refresh changes

By the engineer who builds Datadef, from client work on data platforms · Reviewed August 21, 2026

Two of the tools on the Datadef MCP server exist only for diagrams linked to a repository, and they behave differently from every other tool on the server: one is read-only and free, the other regenerates a diagram and is marked destructive. This is the reference for both, written for whoever is deciding what an agent is allowed to call unattended.

Try it free
6 min readFor anyone writing agent rules around the two repository tools

See it as a diagram

Everything below, as a diagram you can edit. Describe yours and see it in seconds.

138/2000• 3 credits left
Try:

No account needed · Editable canvas, not a picture

The two tools

Two of the thirty-six tools on the server, which is nine outcome-level tools plus the twenty-seven atomic canvas tools. repo_status takes the project id of a repo-linked diagram and reports the link: which provider and repository it tracks, which branch or tag, the commit it currently reflects, when it last synced and with what result, whether daily sync is on, and a plain freshness reading. It is annotated readOnlyHint, so a client that gates writes behind approval lets it through as a routine check.

repo_refresh takes the same id and triggers a sync. If the tracked ref has not moved, it comes back in a couple of seconds saying the repository is still at the same commit and nothing changed. If it has moved, the diagram is regenerated from the repository, which typically takes one to three minutes.

Because generation outlives a comfortable tool call, repo_refresh races the sync against a ten second timer and hands control back with a started message pointing at repo_status when the timer wins. The pattern that works is call refresh, keep working, poll status once, rather than blocking on a single call. repo_refresh is annotated destructiveHint, and it means it: a real regeneration replaces the canvas content, so a client that asks before destructive calls is asking a fair question.

repo_status(project_id) returns

  projectId         the id you passed, resolved from a diagram id
  projectName       "Platform architecture"
  provider          github | gitlab | azure_devops
  repo              acme/platform
  refType/refName   branch main   (or tag v3.2.0)
  lastCommitSha     8f21c0ad12...
  lastSyncedAt      2026-08-20T04:11:07Z
  lastSyncStatus    ok | running | failed | awaiting_focus
  lastSyncError     the message, when the last run failed
  connectionStatus  ok | auth_failed | not_found
  syncDaily         true | false
  freshness         a plain-language reading of the age

Returned both as prose and as structuredContent, so an agent
can branch on the fields without parsing the sentence.

The guardrails

Ownership is checked on every call: the API key behind the MCP session has to own the repository connection, so an agent cannot refresh a linked diagram belonging to someone else. Repository links themselves are created in the app rather than from an agent, which keeps the token entry and the scope choice in a place a person is looking at.

Refreshes are rate limited to ten per ten minutes per user, and the bucket is shared with manual refreshes from the app, because an agent looping over a list of projects would otherwise start a dozen multi-minute generations at once. Hitting the limit answers with the number of seconds to wait rather than failing the diagram.

The first sync of a brand new link is a special case. It reads the repository, then parks and asks what the diagram should show, unless the repository is Terraform-dominant, which has no question to ask. An agent calling repo_refresh against a parked link is told the choice is pending and answerable on the canvas. It resolves itself either way: after ten minutes of grace the recommendation becomes the answer and the sync continues, with the hourly sweep as the backstop if the process that held the timer restarted.

The messages are written to be actionable rather than decorative, because an agent has to route on them. A project with no link answers "No repository link found for that project, or your key does not own its connection. Repo links are created at datadef.io in the dashboard." A refresh past the limit answers "Too many syncs at once. Try again in N seconds." Neither is an exception the agent has to interpret.

What these two tools cannot do

They cannot create anything. A connection and a link are made in the app, where a person enters the token and picks the scope, and no tool on the server accepts a repository URL. An agent pointed at an unlinked project gets a not-found rather than an offer to connect one.

They cannot choose the view. The focus question asked at first sync is answered on the canvas, not through a tool argument, so an agent cannot decide that a repository should be documented as its data content rather than its infrastructure.

And repo_refresh is not an editing tool. It regenerates from the repository, so it belongs to diagrams whose truth lives in code. A hand-arranged canvas that happens to be linked is better served by turning its daily sync off, as covered in manual edits on a synced diagram. The rest of the server, creation, editing, export and the canvas tools, is described on the agents page, with per-client setup in the MCP documentation.

Deciding when to call them

This page is the reference for the tools themselves. For the judgment of which call a post-merge loop should make, and when the right answer is no call at all, see update the diagram after a merge.

FAQ

Which MCP tools cover repository-linked diagrams?

Two. repo_status reports which repository and ref a diagram tracks, the commit it reflects, its last sync result, whether daily sync is on, and how fresh it is. repo_refresh triggers a sync of that diagram from the current state of the repository.

How long does an agent-triggered sync take?

If the tracked ref has not moved, a couple of seconds and no regeneration. If it has, one to three minutes typically. The refresh call waits about ten seconds and then returns a started message, so the agent should poll the status tool rather than block.

Can an agent create a repository connection?

No. Connections and links are created in the app, where the token and its scope are entered by a person. Agents can check status and trigger a re-sync of links that already exist, and only for connections owned by the account behind the API key.

Is there a limit on how often an agent can trigger a sync?

Yes, ten syncs per ten minutes per user, shared with the manual refresh button in the app. It exists so an agent iterating over many projects cannot start a dozen multi-minute generations at once. Exceeding it returns the number of seconds to wait rather than putting the diagram into an error state.

Which agent clients can use these tools?

Any MCP client that can connect to the Datadef server, including Claude Code, Cursor, Claude Desktop, and ChatGPT. The repo tools are two of thirty-six: nine outcome-level tools for creating, reading, editing and exporting diagrams, plus twenty-seven atomic canvas tools for building one node by node.