See it as a diagram
Everything below, as a diagram you can edit. Describe yours and see it in seconds.
No account needed · Editable canvas, not a picture
The entry, and the key name that trips people up
VS Code uses a top-level servers object in mcp.json. Cursor and Claude Desktop use mcpServers. The files look alike enough that a working Cursor block pasted into VS Code produces no error and no server, which is a slow half hour if you do not know the difference. The Datadef settings page generates the VS Code form specifically, so copy from there rather than from another client.
Put the file at .vscode/mcp.json inside a repository when the team should get the server with a checkout, or add it to your user settings when the setup is personal. The workspace file is committable, and VS Code asks for confirmation before starting servers defined by a workspace, which is the behaviour you want for something arriving through a pull request.
The entry runs mcp-remote as a local stdio bridge to the remote endpoint, carrying the Authorization header through. VS Code also offers a one-click install link from the Datadef settings page, which writes the same entry.
// .vscode/mcp.json
{
"servers": {
"datadef": {
"type": "stdio",
"command": "npx",
"args": [
"-y", "mcp-remote", "https://datadef.io/mcp",
"--header", "Authorization: Bearer dd_live_YOUR_KEY"
]
}
}
}Keeping the key out of the committed file
A workspace mcp.json with a literal key in it is a credential in git history. VS Code supports input variables in mcp.json, which prompt for a value on first use and store it outside the file, and it reads environment variables, so the committed entry can reference a placeholder instead of the secret.
There is a product reason as well as a hygiene one. A Datadef key resolves to one account, and every diagram a tool call creates lands in that account. Sharing one key across a team makes a single person the owner of everyone's diagrams, and the per-credential activity list in settings then shows one label for the whole team instead of who did what.
Using it in a session
Open the chat view in agent mode and check the tool picker: connected servers appear there with their tools, and Datadef contributes 36. The nine whole-diagram tools handle creating, reading, editing, exporting, and repository sync, and the 27 canvas tools do the element-level work.
A useful sequence in an editor is narrow rather than broad. Ask the agent to read the design guide, then to draw one bounded thing, a single service and its dependencies rather than the entire estate, and to finish by validating the canvas. Validation reports orphan nodes and overlaps, and measurement reports the size, which is the part a model cannot assess about its own output.
What comes back is a project in your Datadef workspace rather than a file in the repository. Open it on the canvas, correct what the code could not tell the agent, and put it in the README as a live image if it should stay visible to everyone.
One endpoint, every client
After the agent draws it: what keeps it true
A diagram an agent produced once is a diagram that starts aging the same afternoon. Connecting the repository read-only from GitHub, GitLab or Azure DevOps on a branch or tag moves the job to a daily sync that regenerates the diagram and an architecture.md, and repo_status and repo_refresh let the session in agent mode close the gap between a merge and the next scheduled run.
The sync does not redraw for the sake of redrawing. Before generating, it hashes what actually feeds the diagram, the parsed Terraform draw plan or the assembled file corpus, and compares that fingerprint with the previous run. A commit that touches only tests, comments or a README moves the commit sha and leaves the fingerprint identical, so the run stops there at zero cost. When the structure did change, the previous diagram's node ids, labels and zone names go into the prompt with an instruction to reuse them, and any node someone dragged more than twelve pixels from where the last sync left it keeps its coordinates.
That combination is what makes it safe to put the diagram in a README where a whole team looks at it. See repo to diagram for what the sync reads and how far back it looks.
FAQ
Where does VS Code read MCP servers from?
Why does my Cursor MCP config not work in VS Code?
How do I avoid committing an API key in mcp.json?
Where do the tools show up once the server is registered?
Does the diagram end up as a file in my repository?