MCP Setup

The Zindex MCP server gives AI agents direct tool access to the Diagram Scene Protocol (DSP) - scene lifecycle (create, edit, render), validation, revision history, and soft-delete recovery. See the MCP Tools reference for the full list and contracts.

It’s a thin HTTP client that talks to the Zindex API. With an API key configured, every persisted operation goes to the cloud, giving you revision history, multi-session sceneId references, visual diff, and durable links. Without a key the server still starts in anonymous mode and exposes the public-endpoint tools (dsp_validate_scene, dsp_normalize_scene, dsp_render_scene with inline scenes only) for quick demos and one-off renders.

Install the MCP server below and you’re done - the server emits the persist-first workflow and core rules via the MCP instructions field on connect, and compatible hosts (Claude Desktop, Cursor, Claude Code, VS Code Copilot Chat, Continue, etc.) pass this to the connecting agent automatically. The instructions describe both modes; agents read which one they are in via tools/list.

Building an agent integration? Read How AI Agents Should Use Zindex for the recommended tool usage pattern, scene lifecycle, and conflict recovery behavior. For a ready-to-paste system prompt, fetch the canonical agent front door.

Two modes

The MCP server runs in one of two modes depending on whether ZINDEX_API_KEY is set in your host config:

• Authenticated mode (key set): the full MCP tool set is available. Persisted scenes with stable sceneIds, immutable revisions, visual diff between revisions, and the full DSP tool surface. Recommended for any workflow that edits a diagram more than once.
• Anonymous mode (no key): only the public-endpoint tools register (dsp_validate_scene, dsp_normalize_scene, dsp_render_scene with inline scenes only). Runs against api.zindex.ai/v1/scenes/{validate,render,normalize} with no auth header, rate-limited 30/min per IP. Use this to demo the engine, render one-off diagrams, or feasibility-test before the user has a key.

You can install the server with no key configured and it will start in anonymous mode. Add ZINDEX_API_KEY later (free at zindex.ai/signup) to upgrade to the full tool set without changing anything else in your host config.

Prerequisites

• Node.js 18+ - required to run the MCP server
• (Optional) A Zindex API key - free, takes 30 seconds, see below. Skip this if you only want anonymous mode.

1. (Optional) 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. Skip this step if you only want to try anonymous mode (validate / normalize / inline-scene render with no signup).

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 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

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

Environment variables

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:

1. dsp_create_scene - initialize the diagram (returns a persisted sceneId)
2. dsp_apply_ops - add nodes and edges (each call = new revision)
3. dsp_normalize_scene - resolve layout and compute edge routing
4. 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

Server starts in anonymous mode but you wanted persisted scenes You did not set ZINDEX_API_KEY in your host config (or the env block did not reach the spawned process). The startup banner on stderr names the active mode. Add the key under env.ZINDEX_API_KEY and restart the host. Get a free key at zindex.ai/signup.

Persisted-scene tools (dsp_create_scene, dsp_apply_ops, etc.) are missing from tools/list You are in anonymous mode. Those tools are not registered without a key (the underlying endpoints would return 401). Set ZINDEX_API_KEY and restart to upgrade to the full MCP tool set.

Connection refused / 401 Unauthorized in authenticated mode 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.