Generate a diagram inside a chat session, and keep it afterwards

Datadef runs a remote MCP server at https://datadef.io/mcp over Streamable HTTP. Clients reach it two ways. ChatGPT and other OAuth clients add the URL as a connector and sign in to Datadef when prompted, so no key is pasted anywhere. Clients that authenticate with a header send an API key as a bearer token.

Claude Code takes one command, and the transport flag is not optional: without --transport http the URL is treated as a local command and the server never appears in the session. Claude Desktop and other clients that only speak stdio bridge through mcp-remote, which forwards the Authorization header to the remote server.

You can read the tool surface before creating anything. The handshake and the listings are anonymous: initialize, ping, tools/list, prompts/list and resources/list answer a request with no Authorization header at all, which is what lets a directory crawler score the server and lets a curious agent inspect the 36 tools before its human has a key. Only tools/call sits behind authentication.

API access comes with paid plans, and the key is created on the MCP and integrations page and shown once. The plan behind a key is re-checked on every request rather than trusted from the moment the key was minted, so a credential stays cryptographically valid after a subscription lapses and stops working the same day. That case does not report as an expired token: the server rewrites the challenge to say the trial or subscription has ended, that the diagrams are intact and viewable in the dashboard, and that the credential itself is still valid and needs no re-authorisation. Without that rewrite, clients word a generic 401 as re-authorise and send a paying customer round a loop that cannot succeed.

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

# the tool surface, before any key exists
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"}'

# then, in the session
> list my diagrams

A diagram is only as detailed as the description behind it. Naming the actual technologies, Snowflake, dbt, Airflow, Kafka, Fivetran, produces a diagram with the right icons and the right vocabulary. Naming the zones you want matters even more, because zone names in the request are treated as a specification rather than a hint, so "one zone per medallion layer" is honoured rather than interpreted.

Scope is the other lever. The default, overview, produces roughly 12 to 20 nodes and answers the question most people are actually asking. Detailed itemises everything and is denser to read, which is occasionally what you want and usually not what a one-line request deserves. A good agent asks before choosing detailed, because a 40-node diagram from an open-ended prompt is impressive and rarely useful.

One request per diagram. Chat sessions encourage piling requirements into a paragraph, and a diagram that tries to be an overview and a table-level model at once is neither. Generate the overview, then ask for the detail as an edit on the diagram that exists.

Generation waits about 35 seconds inline. Fast ones come back finished with a preview image and a link. Slower ones return a diagram id and keep going for one to three minutes in the background, which is where sessions go wrong: the model sees no image, assumes failure, and calls create_diagram again. That produces two diagrams and spends a second credit.

The correct behaviour is to poll get_diagram with the returned id, roughly every 30 seconds, until the generation reports finished. When a client cannot make further calls on its own, the useful fallback is to hand over the link and say the diagram will be ready in about a minute, rather than leaving the request looking failed.

The result is a project in your Datadef account, not an artifact of the conversation. It opens in the editor with the same canvas the generator produced, so the next change is a two-second drag rather than a re-prompt. It exports to PNG or JPEG. It embeds as a live image in a README or a wiki page, and it can be shared with people who have no account.

That property is the reason to route chat-generated diagrams through a real tool at all. An image generated in a chat is finished the moment it appears: any change means describing the whole thing again, and there is no version anyone else can open. A diagram that lands in a workspace is where the second, third and tenth revision happen.

• Datadef for AI agents
• MCP and agents: per-client setup
• The MCP diagram server, in depth
• Connect Claude Code to a diagram tool
• The Datadef editor