MCP Client Guide

n8n MCP Client for diagrams: transport, credential, and the wait step

By the engineer who builds Datadef, from client work on data platforms · Reviewed August 21, 2026

n8n can call an MCP server as a tool inside an AI Agent node, which turns diagram generation into something a workflow does rather than something a person asks for. The wiring is three fields. The part that catches people is timing: one of these tools can take longer than a node is willing to sit still for, and the server is explicit about what to do instead.

Try it free
7 min readFor n8n builders adding diagram generation or repository sync to an automated workflow

See it as a diagram

Everything below, as a diagram you can edit. Describe yours and see it in seconds.

158/2000• 3 credits left
Try:

No account needed · Editable canvas, not a picture

The three fields that connect it

Add an MCP Client Tool node and attach it to an AI Agent node as a tool. Set the transport to HTTP Streamable rather than SSE: SSE is the legacy option, and the Datadef endpoint speaks streamable HTTP. Set the endpoint to https://datadef.io/mcp. For authentication, pick bearer and store a Datadef API key in the credential rather than typing it into the node, so it does not travel in an exported workflow.

The node fetches the tool list from the server, which works because listings on this endpoint are anonymous: initialize, ping and tools/list answer with no credentials, so the node can populate its tool selector even before the credential is right. Tool calls are the part that needs the key.

Then narrow the selection. An agent given all 36 tools in a workflow context will happily spend a run exploring canvas primitives. For an automation, expose the two or three tools the workflow actually needs and leave the rest off.

MCP Client Tool node
  Transport      HTTP Streamable
  Endpoint       https://datadef.io/mcp
  Authentication Bearer
  Credential     Datadef API key (dd_live_...)
  Tools          repo_status, repo_refresh, export_diagram

The timing problem, and the shape that solves it

Generation is not instant. create_diagram waits about 35 seconds and returns a finished diagram if it lands inside that window. When it does not, the call returns a diagram_id immediately with the diagram still being produced, and the correct next move is to wait roughly a minute and call get_diagram with that id, polling every 30 seconds. Calling create_diagram again instead produces a duplicate diagram and spends a second credit.

In n8n that maps onto a familiar shape: the create call, a Wait node, then a get call, with a loop back to the wait while the status is still running. Building it as one impatient node is what turns a working setup into an intermittent one, because fast generations succeed and slow ones look like failures.

Repository sync has its own limit. Refreshes share a bucket of ten per ten minutes per account, so a workflow that loops over many linked projects should pace itself rather than fan out. A refresh also regenerates the diagram from the repository, which replaces manual canvas edits, so it belongs in a workflow only for projects whose diagram is meant to be generated rather than hand-tuned.

Workflows that are worth building

A post-merge freshness check is the highest-value one. On a merge webhook, call repo_status for the linked project, and only if the last sync predates the merge, call repo_refresh. Datadef already syncs connected repositories daily on its own, so the workflow exists to close the gap between a merge and the next scheduled run, not to replace it.

A second good one is documentation delivery. export_diagram takes a viewport width from 600 to 4000 and a height from 400 to 4000, defaulting to 1600 by 1000, and returns three things: the rendered PNG or JPEG, a signed download link valid for 15 minutes that serves the file with an attachment header and needs no API key, and, when the project is shared publicly, a permanent image URL with a ready-made markdown line. The download link is what a workflow attaches to a message. The permanent URL is what it writes into a wiki page, because that one keeps matching the canvas instead of freezing on the day the workflow ran.

A third is intake. A form or an issue template describing a proposed system, passed to create_diagram, gives a reviewer a picture instead of a paragraph. Keep the scope at overview, since a dense diagram from a one-paragraph description is rarely what anyone wanted.

Every call is attributed

Tool calls made by a workflow appear in the agent activity list in Datadef settings with the credential label, the tool, the status and the duration, so an automation that misbehaves is visible without reading prompts. See the MCP documentation.

FAQ

Which n8n node calls an external MCP server?

The MCP Client Tool node, attached to an AI Agent node as one of its tools. It supports both SSE and HTTP Streamable transports and several authentication methods, including bearer, generic header and OAuth2. Store the Datadef API key in an n8n credential rather than typing it into the node, so it does not travel inside an exported workflow.

Which transport should the node use for this server?

HTTP Streamable. SSE is the legacy transport and this endpoint speaks streamable HTTP, so a mismatched transport is the most common reason the connection appears to do nothing. The endpoint is https://datadef.io/mcp, and the node can populate its tool selector before the credential is even valid, because listings on this server answer anonymously.

Why does the tool list load before the credential is valid?

Because the handshake and the listings on this server are anonymous. initialize, ping and tools/list answer without credentials so directories and clients can inspect the tool surface, while tool calls require a key or an OAuth token. A tool selector that fills in is therefore not proof that the credential works. The first tools/call is the proof.

How should a workflow handle a diagram that takes minutes to generate?

The generation call waits about 35 seconds and returns a finished diagram if it fits. Otherwise it returns a diagram id straight away, and the workflow should wait about a minute and then poll the read tool with that id every 30 seconds. Repeating the generation call instead creates a duplicate and spends another credit.

Is there a rate limit on repository refreshes?

Yes. Refreshes share a bucket of ten per ten minutes per account, which stops a workflow looping over many linked projects from starting unbounded syncs. A refresh regenerates the diagram from the repository and replaces manual canvas edits, so use it only where the diagram is meant to be generated.