MCP Client Guide

Cursor MCP config for a diagram server: the JSON, the deep link, the scope

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

Cursor reads its MCP servers from a JSON file, and the entry for a remote server looks different from the entry for a local one. This page gives the exact block for Datadef, the one-click alternative, and the choice between a config that follows you and a config that follows the repository.

Try it free
6 min readFor Cursor users adding a remote MCP server by hand or rolling one out to a project

See it as a diagram

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

185/2000• 3 credits left
Try:

No account needed · Editable canvas, not a picture

Two files, two blast radiuses

Cursor looks for MCP servers in ~/.cursor/mcp.json, which applies to every project you open, and in .cursor/mcp.json inside a project, which applies to that repository only. The project file is the one to commit when a team should get the same servers; the home file is the one to use for a personal setup you do not want to explain to anyone.

Datadef runs as a remote Streamable HTTP endpoint. Desktop clients that speak stdio reach it through mcp-remote, a small local bridge that forwards every request to the remote URL along with the Authorization header. That is the form the Datadef settings page generates, and it is the safest one to paste because it works regardless of which HTTP transports your Cursor build supports.

Create the key first on the MCP and integrations page. It is shown once. After saving the file, reload Cursor and open the MCP section of settings: a connected server lists its tools, and Datadef reports 36 of them.

// ~/.cursor/mcp.json for every project, or
// .cursor/mcp.json inside one repository
{
  "mcpServers": {
    "datadef": {
      "command": "npx",
      "args": [
        "-y", "mcp-remote", "https://datadef.io/mcp",
        "--header", "Authorization: Bearer dd_live_YOUR_KEY"
      ]
    }
  }
}

The one-click install, and what it actually writes

Cursor accepts an install deep link, and the Datadef settings page offers one next to the JSON. The link carries the server object base64 encoded in a config parameter on a cursor://anysphere.cursor-deeplink/mcp/install URL, so clicking it writes the same entry shown above without you touching a file.

The deep link is convenient for one machine and a poor fit for a team, because the encoded payload includes your key. For a repository rollout, prefer the project file with the key kept out of it, and let each person supply their own credential. Diagrams created through a key land in that key's account, so a shared credential quietly makes one teammate the owner of everyone's work.

What the Cursor agent can do with it

The coarse moves are single tools: create_diagram from a description, get_diagram to read one back, edit_diagram to apply a plain-language change, export_diagram for a PNG or JPEG plus a signed download link. For a project that is connected to a repository, repo_status reports which branch or tag it tracks and how stale it is, and repo_refresh regenerates it.

The 27 canvas tools are the reason a Cursor session can produce something presentable rather than a graph dump. canvas_add_nodes and canvas_connect_nodes build, canvas_group_nodes creates zones, canvas_set_columns fills table structures, canvas_add_lineage draws column-level relationships, canvas_search_icons finds the real provider marks, and canvas_layout_canvas arranges the result.

Ask for get_design_guide at the start of the session. It returns the same size, edge and zone standard the Datadef generator follows, which is what keeps an agent-built diagram from looking foreign next to a generated one in the same workspace. The result is a normal project you can open on the canvas and embed as a live image.

Reload, then read the tool count

Cursor loads its server list at startup. A saved file with no reload looks exactly like a broken config. If the count still reads zero after a reload, test the endpoint itself: tools/list answers anonymously on this server, so a listing that works proves the problem is local.

The icon set behind canvas_search_icons

That one tool decides whether an agent-built diagram looks like your stack or like a flowchart. It searches 2,098 provider icons shipped as individual SVG files: 439 for AWS, 624 for Azure, 226 for Google Cloud, and the remainder across data tooling, Kubernetes, networking and general infrastructure. An agent that searches before it adds nodes gets the Snowflake mark and the Kafka mark. One that does not gets grey boxes with words in them.

The same registry backs the Terraform pipeline, and the mapping between resource types and icons is asserted rather than hoped for: every icon id in the Terraform type catalog has to exist in the icon registry, and a test script fails on a typo instead of letting a generic glyph reach a production diagram. Where a cloud resource type is not in the explicit table, it falls back to the Terraform mark rather than a guessed service icon, on the reasoning that a wrong AWS icon lies while terraform-managed is always true.

A prompt habit follows from this. Name the technologies rather than the roles: asking Cursor for the warehouse gets a generic database, asking for Snowflake gets Snowflake.

FAQ

Where does Cursor store MCP server configuration?

In ~/.cursor/mcp.json for every project, and in .cursor/mcp.json inside a specific repository. Both use a top-level mcpServers object. The project file is the one to commit when a whole team should get the same servers. Keep the key itself out of that file, because a Datadef key resolves to one account and every diagram a tool call creates lands there.

Why does the Cursor entry run npx mcp-remote instead of pointing at the URL?

mcp-remote is a local stdio bridge that forwards requests to a remote HTTP endpoint, including the Authorization header. Using it means the entry works on any Cursor build regardless of which remote transports that build supports natively, which is why it is the recipe the Datadef settings page generates.

What does the Cursor one-click install link contain?

A cursor://anysphere.cursor-deeplink/mcp/install URL with the server object base64 encoded in its config parameter. Clicking it writes the same entry you would paste by hand. Because the payload embeds the API key, it suits one machine rather than a team rollout.

How do I confirm the server registered?

Reload Cursor and open the MCP section of settings. A connected server lists its tools; the Datadef entry reports 36, made up of nine whole-diagram tools and 27 canvas tools. A count of zero after a reload usually means the JSON is in the wrong file or the key is mistyped.

Can the agent edit a diagram that already exists?

Yes. It can list the workspace, read a specific diagram back with its nodes, edges and groups, then either apply a described change in one call or drive individual canvas operations such as adding a node, relabelling an edge, or moving something into a zone.