Claude Code MCP server for diagrams: the command, the scope, the 36 tools

Create an API key on the MCP and integrations page in Datadef settings. The key is displayed once at creation and cannot be read back later, only revoked and replaced. Then register the server from your terminal and restart Claude Code.

The transport flag is mandatory. Without it, claude mcp add treats the URL as a stdio command and tries to execute it as a binary. Nothing fails loudly; the server simply never appears, which is why most reports of a broken MCP server are a missing flag.

Datadef is a remote Streamable HTTP server, so Claude Code talks to it directly over HTTP and no local bridge process is involved. Inside a session, /mcp lists the connected servers and their tool counts; a healthy Datadef entry reports 36 tools.

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

# then restart Claude Code and, inside a session:
/mcp

The default registration is local: this project, your machine, invisible to anyone else. Adding --scope user makes the server available in every project you open. Adding --scope project writes a .mcp.json at the repository root, which you commit, and every teammate who pulls the repo is offered the same server.

Do not commit the key itself. Claude Code expands environment variables inside .mcp.json, including in the headers field, so the committed file can reference a variable each person sets in their own shell. That is not only hygiene: a Datadef key is tied to one account, and every diagram a tool call creates lands in that account, so a shared key would pile the whole team's diagrams into one person's workspace.

Datadef records who did what per credential. The agent activity list in settings shows one row per tool call with the credential label, the tool name, the status, and the duration, so a team registration stays auditable without anyone reading prompts. Argument excerpts are capped at 140 characters and full prompts are never stored.

// .mcp.json at the repository root, safe to commit
{
  "mcpServers": {
    "datadef": {
      "type": "http",
      "url": "https://datadef.io/mcp",
      "headers": { "Authorization": "Bearer ${DATADEF_API_KEY}" }
    }
  }
}

Nine tools work on whole diagrams: create_diagram generates one from a description, create_blank_diagram opens an empty canvas for the agent to build itself, list_diagrams and get_diagram read the workspace, edit_diagram applies a plain-language change, export_diagram renders PNG or JPEG, repo_status and repo_refresh drive repository sync, and get_design_guide returns the design standard.

Twenty-seven canvas tools carry the prefix canvas_ and do the fine work: adding and updating nodes, connecting and relabelling edges, grouping into zones, setting table columns, drawing column-level lineage, aligning and laying out, and validating the result. canvas_validate_canvas and canvas_measure_canvas matter more than they sound, because size and overlap are exactly what a text-only model cannot judge about its own output.

Timing is worth knowing before you script anything around it. create_diagram waits about 35 seconds and returns a finished diagram when generation lands inside that window. When it does not, you get a diagram_id straight away and the agent is told to call get_diagram after roughly 60 seconds, polling every 30. A tool call can run for up to five minutes in total.

The handshake and the listings on the Datadef endpoint are anonymous. initialize, ping, tools/list, prompts/list and resources/list answer with no credentials at all; only tools/call requires authentication. That gives you a one-line test that separates a server problem from a client problem, runnable before a key exists.

If the listing comes back and the session still shows nothing, the cause is local: the transport flag, a client that was not restarted, or a scope that put the entry somewhere this project does not read. If tool calls fail while listings work, the credential is the suspect. A rejected key that is genuinely valid but attached to a lapsed plan gets a specific answer rather than the generic challenge, so the client says the subscription ended instead of sending you round a re-authorization loop that could never work.

curl -s https://datadef.io/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

• MCP server documentation and client setup
• Connect Claude Code to a diagram tool
• The MCP diagram server, in depth
• Draw diagrams with your AI agent over MCP
• Repo to diagram: repository sync