Keep in sync

MCP and agents

Your AI agent already knows your architecture from the code; connected to Datadef, it can draw it without you leaving the chat or editor. Datadef runs a remote MCP server at https://datadef.io/mcp (Streamable HTTP, bearer auth): an agent connected to it can create diagrams from a description, edit an existing diagram node by node, export images, and refresh repo-linked diagrams. Agent-built diagrams follow the same design standard as Datadef's own generator, so they land in your workspace looking like yours.

The MCP and integrations settings page: create an API key, pick a client such as Claude Code, Cursor, or VS Code, and copy the prefilled setup command
Setup lives in the app: one key, one snippet per client.

How it works

  1. 1Create an API key on the MCP & integrations page. API access comes with paid plans, and the key is shown once.
  2. 2Pick your client and copy the prefilled snippet: one command for Claude Code, one-click for Cursor and VS Code, OAuth for ChatGPT.
  3. 3Ask the agent for a diagram. It calls create_diagram, edit_diagram, and the canvas tools against your account.
  4. 4The result is a normal project in your dashboard: editable, shareable, embeddable, versioned.

Setup

Everything happens on MCP & integrations in the app: create an API key (shown once, so copy it there), pick your client, and copy the prefilled snippet. API access is available on paid plans, and the key stops authenticating while the plan is lapsed.

Claude Code

claude mcp add --transport http datadef https://datadef.io/mcp \
  --header "Authorization: Bearer dd_live_YOUR_KEY"

The --transport http flag is required; without it the URL is treated as a local command and the server never appears.

Cursor, VS Code, Claude Desktop, Codex, Gemini CLI

The settings page has a one-click install for Cursor and VS Code and copy-paste config for the rest. Desktop clients that only speak stdio bridge through mcp-remote, which forwards the Authorization header:

{
  "mcpServers": {
    "datadef": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://datadef.io/mcp",
               "--header", "Authorization: Bearer dd_live_YOUR_KEY"]
    }
  }
}

ChatGPT and other OAuth clients

Datadef's MCP endpoint is also an OAuth 2.1 authorization server, which is the flow ChatGPT connectors require. Add https://datadef.io/mcp as a connector and sign in to Datadef when prompted; no API key is pasted anywhere. Any other client that speaks Streamable HTTP can connect either way: OAuth, or the URL plus an Authorization: Bearer header.

The tools

ToolWhat it does
create_diagramGenerate a full diagram from a prompt. Takes a scope (overview or detailed) and saves to your account.
create_blank_diagramCreate an empty diagram for an agent to build up tool call by tool call.
list_diagramsList the diagrams the key’s account can access.
get_diagramRead a diagram, including generation status while one is running.
edit_diagramApply a described change to an existing diagram.
export_diagramRender PNG or JPEG, returned inline plus a signed download URL.
repo_statusFor a repo-linked project: connection, ref, last sync, freshness.
repo_refreshTrigger a sync of a repo-linked project.
get_design_guideDatadef’s diagram design standard, for agents building by hand.
canvas_*27 atomic tools: read and inspect, add and update nodes, connect, group into zones, set table columns, add lineage, annotate, lay out, validate.

One standard for humans and agents

get_design_guide returns the same size, edge, and zone standard the generator follows. An agent that reads it first produces diagrams indistinguishable from generated ones, so hand-built and generated diagrams mix in one workspace without a style split.

The regeneration loop

The point of the MCP surface is diagrams that track the code. An agent with repo access can regenerate or patch a diagram after a merge, on a schedule, or when asked during review. Datadef itself does not watch your repositories; the loop is agent-invoked or CI-invoked, one call away. For sync that Datadef schedules on its own, use a repository connection, whose daily refresh runs server-side.

Further reading