io.datadef/mcp

Draw one large labelled arrow representing a whole flow — "ingest", "serve", "publish" — instead of many thin edges saying the same thing. Use this when several things move the same way for the same reason: draw the arrow once between the two areas rather than connecting every pair. This is a visual annotation, not a connection, so it adds no edges and no fan-out. Position it in the gap between the two areas using canvas_measure_canvas. Operates on one Datadef diagram, named by diagram_id.

Record column-level lineage: which source column produces which target column, and how. This is what makes the diagram queryable for impact analysis, so add it for every real transformation. Operates on one Datadef diagram, named by diagram_id.

Add one or more nodes to the canvas. Batch every node you want in a single call. Positions are assigned by canvas_layout_canvas afterwards — never set them yourself. Operates on one Datadef diagram, named by diagram_id. If you have not already, call get_design_guide first: it carries Datadef's size, edge, and zone standard, and diagrams built without it read poorly.

Draw a labelled translucent area behind existing nodes to show they belong together, without reparenting them. Use this when the grouping is a reading aid rather than real containment, when areas would need to overlap, or when a node belongs to two ideas at once — canvas_group_nodes cannot express any of those because it moves nodes into the zone. Call canvas_measure_canvas first and size the region to enclose the nodes with roughly 24px of margin. Operates on one Datadef diagram, named by diagram_id.

Place a rectangle, circle, arrow, or line as a visual annotation — a backdrop highlighting a region, an arrow pointing something out, a divider. Shapes sit behind data nodes and are not part of the data flow. To group nodes into a labelled zone use canvas_group_nodes instead. Operates on one Datadef diagram, named by diagram_id.

Add a single data node at an exact position, without connecting it to anything. Use when the user wants something placed somewhere specific, or when you will wire it up yourself afterwards. For building out a connected diagram, canvas_add_nodes is better — it batches and lets layout position everything. Operates on one Datadef diagram, named by diagram_id.

Place a free-floating text box on the canvas — a caption, a callout, a section heading, a note explaining a decision. Position it with explicit coordinates from canvas_measure_canvas. Text boxes are annotations: they are not part of the data flow and take no edges. Operates on one Datadef diagram, named by diagram_id.

Align nodes to a shared edge or centre line, or space them evenly. Cleaner and far more reliable than computing coordinates by hand. Operates on one Datadef diagram, named by diagram_id.

Merge several nodes into one summary node, keeping every connection. Use when a set of near-identical objects adds length without adding meaning — eight staging models that all behave the same become "stg_* (8)". Do not use when the individual objects are what the reader came for. Operates on one Datadef diagram, named by diagram_id.

Draw edges between nodes to show how data flows. Always label the edge with what actually happens ("ingest", "dbt transform", "hourly sync") — unlabelled edges make a diagram useless. Operates on one Datadef diagram, named by diagram_id.

Get an overview of the current canvas: every node with its id, type, label and group, plus all connections and groups. Call this first, before any edit, so you work from real node ids instead of guesses. Operates on one Datadef diagram, named by diagram_id. If you have not already, call get_design_guide first: it carries Datadef's size, edge, and zone standard, and diagrams built without it read poorly.

Remove the edge between two nodes. Operates on one Datadef diagram, named by diagram_id.

Create a labelled zone (e.g. "Bronze Layer", "Ingestion") and optionally move nodes into it. Zones are what turn a tangle of boxes into a readable architecture — use them for layers, domains, or environments. Operates on one Datadef diagram, named by diagram_id. If you have not already, call get_design_guide first: it carries Datadef's size, edge, and zone standard, and diagrams built without it read poorly.

Get full detail for specific nodes: all columns with types and keys, metadata, schedule, formula, owners. Use before modifying a node so you preserve fields you are not changing. Operates on one Datadef diagram, named by diagram_id.

Arrange the canvas. Call this once at the end, after all structural edits are done — not between each edit. By default only the parts you touched are re-arranged and everything else keeps its position. Operates on one Datadef diagram, named by diagram_id.

Get exact geometry: every node's position and size in canvas units, the overall canvas bounds, and any nodes that overlap each other. Call this before moving, resizing, or placing anything precisely — positions are meaningless without it. Operates on one Datadef diagram, named by diagram_id.

Set node positions precisely. Use absolute x/y to place something exactly, or dx/dy to nudge it. Coordinates are absolute canvas units (same space canvas_measure_canvas reports). Moving a group moves its children with it — do not also move those children in the same call. Call canvas_measure_canvas first. Operates on one Datadef diagram, named by diagram_id.

Move existing nodes into an existing group, or out of any group. Operates on one Datadef diagram, named by diagram_id.

Delete nodes and every edge touching them. Deleting a group also deletes the nodes inside it — check with canvas_describe_canvas first if that is not what you want. Operates on one Datadef diagram, named by diagram_id.

Swap a node for a different one while keeping every connection, its position, and its group. Use this when a component changes — Redshift becomes Snowflake, a batch job becomes streaming — instead of deleting and rebuilding, which would lose all the edges. Operates on one Datadef diagram, named by diagram_id.

Set the width and height of nodes. Mostly for shapes, text boxes, and group zones — data nodes size themselves from their content, and resizing one can clip what it displays. Operates on one Datadef diagram, named by diagram_id.

Search Datadef's icon library (2000+ cloud and data-tool logos) for a valid icon id. Use it when you want a specific vendor logo and are unsure of its exact id — passing an invalid id silently falls back to a generic icon. Operates on one Datadef diagram, named by diagram_id.

Set the full column list of a table node, replacing whatever it had. Pass every column you want to keep — this is a replace, not a merge. Mark primary and foreign keys; they are what make a data diagram worth reading. Operates on one Datadef diagram, named by diagram_id.

Report where this canvas could be collapsed — groups of similar nodes that could become one summary node — without changing anything. Use it to decide whether the diagram is denser than it needs to be. Density is not automatically a problem: keep the detail when the detail is the point. Operates on one Datadef diagram, named by diagram_id.

Change existing connections without deleting them: fix a label, change the type, or restyle. Use this to correct a wrong edge label rather than disconnecting and reconnecting. Operates on one Datadef diagram, named by diagram_id.

Change properties of existing nodes. Only the fields you pass are touched; everything else is preserved. To replace a table's columns use canvas_set_columns instead. Operates on one Datadef diagram, named by diagram_id.

Check the canvas for structural problems (disconnected nodes, circular data flow, broken references) and quality problems (unlabelled edges, tables without columns). Call this before you finish, and fix any errors it reports. Operates on one Datadef diagram, named by diagram_id.

Create an empty diagram and return its diagram_id, so you can build it yourself with the canvas_* tools. No AI generation runs and no credit is spent: you draw it. Use this when you want control over the result, or already know the architecture from the conversation. Use create_diagram instead when you want Datadef's model to design the whole thing from a prompt. Call get_design_guide first: it is the standard Datadef's own generator follows, and building without it produces diagrams this tool exists to avoid.

Generate a professional data architecture diagram from a description and save it to the user's Datadef account. Use this for any data-shaped diagram: medallion and lakehouse architectures, ETL/ELT pipelines, streaming topologies, data mesh, warehouse and dimensional models, lineage maps, and data platform designs. Write a specific prompt. Name the actual technologies (Snowflake, dbt, Airflow, Kafka, Fivetran), the layers or zones you want, and the tables that matter, the diagram is only as detailed as the description. Zone names you give are treated as a specification, not a suggestion. SCOPE: if the user's request is open-ended ("diagram our platform", "show me something"), ask them how much detail they want before calling this, or say which scope you chose. Default to scope "overview". A dense 40-node diagram is impressive and usually not what someone wanted from a one-line request; they can always ask you to expand it. TIMING: this waits up to ~35 seconds; fast generations come back finished, with a preview image and a markdown line to show the user. Slower ones (1-3 minutes total) return a diagram_id while generation continues: call get_diagram with that id after ~60 seconds (poll every 30s) to get the finished diagram. If you cannot call tools again on your own, never leave the user empty-handed: give them the Open link, say it will be ready in about a minute, and offer to show the diagram inline when they next ask. Never call create_diagram a second time while one is still generating; you would create a duplicate and spend another credit. Do not use image generation for these. This produces a real, editable diagram.

Change an existing diagram with a natural-language instruction, add nodes, rewire connections, add columns, reorganise into layers, fill in owners and schedules. Be specific about what to change and where. "Add a Kafka topic between the API and the bronze table, labelled 'events'" works; "make it better" does not. Returns a PNG of the updated diagram.

Render a diagram to a PNG or JPEG image. Returns the image inline AND a short-lived signed download URL. Use the inline image to show the diagram; use the URL when the user wants to save it, attach it, or share a link: it serves the file directly and needs no API key.

Datadef's standard for what makes a diagram readable, size, edge discipline, nested zones, annotations, and the tool order for building or editing. Read this BEFORE your first canvas_* call. It is the same standard Datadef's own generator follows, so a diagram you build by hand comes out indistinguishable from a generated one.

Read the full structure of a diagram: every node with its type and columns, every connection, and the groups. Use this before editing so you know what is actually there.

List diagrams in the user's Datadef account, most recently updated first. Use this to find the id of a diagram before editing or exporting it.

Re-sync a repo-linked diagram from the current state of its repository. If the tracked branch or tag has not moved since the last sync, nothing changes. If it has, the diagram is REGENERATED from the repository, which replaces manual canvas edits. Only the owner of the repository connection can use this.

For a diagram that was created from a connected git repository: which repo and branch or tag it tracks, when it last synced, the commit it reflects, and whether daily sync is on. Use repo_refresh to sync it now. Only the owner of the repository connection can use this.