MCP Setup

The Zindex MCP server gives AI agents 8 tools for creating, editing, validating, normalizing, rendering, diffing, and listing revisions of diagrams through the Diagram Scene Protocol (DSP).

It’s a thin HTTP client that talks to the Zindex API. Every operation persists to the cloud, so you get revision history, multi-session sceneId references, visual diff, and durable links out of the box.

Claude Code users: install the MCP server below and that’s all you need - the server advertises the persist-first workflow and core rules to Claude via its instructions field automatically. For a ready-to-paste system prompt, fetch the canonical agent front door.

Using zindex from Claude Desktop, Cursor, or another MCP host? Read How AI Agents Should Use Zindex for the recommended tool usage pattern, scene lifecycle, and conflict recovery behavior.

Prerequisites

Node.js 18+ - required to run the MCP server
A Zindex API key - free, takes 30 seconds, see below

1. Get an API key

Sign up at zindex.ai/signup and create an API key from the dashboard. Keys are prefixed dsp_sk_. The free plan covers most agent workflows; see Pricing for limits.

2. Configure your MCP host

The Zindex MCP package is published as @zindex-ai/mcp on npm. MCP hosts run it automatically via npx - you don’t need to install it manually.

Claude Desktop

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "zindex": {
      "command": "npx",
      "args": ["@zindex-ai/mcp"],
      "env": {
        "ZINDEX_API_KEY": "dsp_sk_..."
      }
    }
  }
}

Restart Claude Desktop. You should see 8 tools prefixed dsp_ available to the agent.

Cursor / Claude Code / other MCP hosts

The configuration pattern is the same - point the host at npx @zindex-ai/mcp with the ZINDEX_API_KEY environment variable set.

Custom agent frameworks

If you’re building a custom agent with the MCP SDK:

import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";

const transport = new StdioClientTransport({
  command: "npx",
  args: ["@zindex-ai/mcp"],
  env: {
    ZINDEX_API_KEY: "dsp_sk_...",
  },
});

const client = new Client({ name: "my-agent", version: "1.0.0" });
await client.connect(transport);

// List available tools
const tools = await client.listTools();

Available tools

Tool	Description
`dsp_create_scene`	Create a new persisted diagram scene. Supports all diagram families, auto-layout, and styles. Returns sceneId + revision 1.
`dsp_apply_ops`	Apply operations (17 types) to a persisted scene. Each call creates a new immutable revision. Pass `message` for revision history.
`dsp_validate_scene`	Validate a scene for structural and semantic correctness (40+ rules). Stateless.
`dsp_normalize_scene`	Normalize a scene - apply defaults, compute layout, resolve edge routing. Stateless.
`dsp_render_scene`	Render a persisted scene to SVG or PNG. Theme: clean/dark/blueprint/sketch. Revision watermark + visual diff via `diffFromRevision`.
`dsp_get_scene`	Retrieve a persisted scene by ID, optionally at a specific revision.
`dsp_diff_scene`	Diff two revisions - returns added, removed, and modified element IDs.
`dsp_list_revisions`	List all revisions with timestamps, messages, and change summaries.

For detailed input/output schemas for each tool, see MCP Tools Reference.

Environment variables

Variable	Required	Default	Description
`ZINDEX_API_KEY`	yes	-	API key for authentication. Get one at zindex.ai/signup.
`ZINDEX_API_URL`	no	`https://api.zindex.ai`	URL of the Zindex API. Override only for staging or self-hosted.

Example interaction

Once configured, ask your AI agent:

“Create an architecture diagram showing an API Gateway connecting to a Database and a Redis Cache”

The agent will use the MCP tools to:

dsp_create_scene - initialize the diagram (returns a persisted sceneId)
dsp_apply_ops - add nodes and edges (each call = new revision)
dsp_normalize_scene - resolve layout and compute edge routing
dsp_render_scene - render to SVG or PNG with revision watermark

Because every scene persists, you can come back next session, ask “show me the diagram from yesterday,” diff it against an earlier revision, or apply a small edit on top - all without rebuilding the JSON.

For a ready-to-paste set of rules to embed in MCP host instructions, fetch the canonical agent front door: curl -H "Accept: text/markdown" https://zindex.ai/ (or paste from https://zindex.ai/_agent-front-door.md if your host can’t set headers).

Troubleshooting

Error: ZINDEX_API_KEY is required The MCP server needs an API key. Get one at zindex.ai/signup and set it in your host config under env.ZINDEX_API_KEY.

Connection refused / 401 Unauthorized Check that ZINDEX_API_KEY is a valid key (prefix dsp_sk_) and hasn’t been revoked. Manage keys in your dashboard.

“command not found” or npx fails Ensure Node.js 18+ is installed: node --version.

Tools not appearing in Claude Desktop Restart Claude Desktop after editing claude_desktop_config.json. Check the MCP server logs in Claude Desktop’s developer tools for the line Zindex MCP server running on stdio [connected to https://api.zindex.ai].

Verify the install without configuring a host

npx @zindex-ai/mcp --help
npx @zindex-ai/mcp --version

Both work without an API key configured.