@zindex-ai/mcp

MCP server for Zindex - agent-native diagram state infrastructure.

Zindex is a stateful diagram runtime for AI agents. Create architecture diagrams, ERDs, workflows, sequence diagrams, org charts, and topology maps from structured data, then patch, validate, diff, and render them as systems change. Not a whiteboard. Not a Mermaid clone. A database-like backend for diagrams with stable IDs, typed operations, semantic validation, immutable revisions, auto-layout, and SVG/PNG rendering.

The package is a thin HTTP client to the Zindex API at api.zindex.ai. The API holds scene state, computes layout, validates, and renders.

Two modes

The server runs in one of two modes depending on whether ZINDEX_API_KEY is set:

• Authenticated mode (key set): the full MCP tool set is available. Persisted scenes with stable sceneIds, immutable revisions, visual diff, soft-delete recovery. The recommended setup for any workflow that edits a diagram more than once.
• Anonymous mode (no key): only the public-endpoint tools are registered (dsp_validate_scene, dsp_normalize_scene, dsp_render_scene with inline scenes only). Runs against the public stateless endpoints with no auth header. 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.

Quick start

1. (Optional) Get an API key

Free, takes 30 seconds: zindex.ai/signup. Keys are prefixed dsp_sk_. Skip this step if you only want to try anonymous mode (see "Two modes" above).

2. Configure your MCP host

Add to your host config (Claude Desktop's claude_desktop_config.json, Cursor's MCP settings, Claude Code's ~/.config/claude/mcp.json, etc.):

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

Restart your host. You should see the dsp_ tools available to the agent. With a key, the full MCP tool set appears; without one (omit the env block entirely), only the public-endpoint tools appear (dsp_validate_scene, dsp_normalize_scene, dsp_render_scene). The startup banner on stderr names the active mode and tool count.

Verifying the install

Without configuring a host, you can sanity-check the package:

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

Both work without an API key. Running npx @zindex-ai/mcp with no key starts the server in anonymous mode (the public-endpoint tools only); with a key set it starts in authenticated mode (the full MCP tool set). The startup banner on stderr names the active mode and tool count.

Available tools

| Tool | Description | |------|-------------| | dsp_create_scene | Create a new persisted diagram scene. Returns sceneId + revision 1. | | dsp_apply_ops | Apply typed operations. Each call creates a new immutable revision. Pass message for revision history. | | dsp_validate_scene | Validate a scene for structural and semantic correctness. 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. Themes, 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, modified element IDs. | | dsp_list_revisions | List revision history with timestamps, messages, and change summaries. | | dsp_delete_scene | Soft-delete a persisted scene. Recoverable for 24 hours via dsp_undelete_scene. Requires confirm: true. The agent must confirm with the human before calling. | | dsp_undelete_scene | Restore a soft-deleted scene during the 24-hour grace window. | | dsp_list_recently_deleted | Enumerate scenes the caller has soft-deleted within the past 24 hours. Used to look up the sceneId when restoring a scene from a previous session. | | dsp_submit_to_support | Submit a persisted scene to Zindex support so admins can view it (sets privacy to support). Optional anonymize flag replaces labels + IDs with same-width random characters. The agent must confirm with the human before calling. | | dsp_publish_scene | Make a persisted scene publicly addressable at https://zindex.ai/s/<sceneId> (sets privacy to public). Anyone with the URL - including search engines and AI crawlers - can view the rendered scene and its source JSON. The agent must confirm with the human before calling. | | dsp_make_scene_private | Revert a scene to private. The public URL stops resolving immediately. Also the canonical "undo" for dsp_submit_to_support. |

The MCP server is self-describing - it emits onboarding instructions and core workflow rules via the MCP instructions field on connect. Compatible hosts pass this to the connecting agent automatically, so no per-agent configuration is required beyond the API key.

Features

These tools call into the Zindex API, which powers multiple diagram families (architecture, workflow / BPMN, ER, sequence, network, orgchart, uiflow), auto-layout, render themes, semantic validation, immutable revisions, visual diff, and a built-in icon library (Lucide + AWS packs).

For the full feature catalog see Supported Diagram Classes, Element Types, Layout Engine, and Rendering.

Environment variables

| Variable | Required | Default | Description | |----------|----------|---------|-------------| | ZINDEX_API_KEY | no | - | API key. Without one the server runs in anonymous mode (public-endpoint tools only). With one it runs in authenticated mode (full MCP tool set, persisted scenes). Free key at zindex.ai/signup. | | ZINDEX_API_URL | no | https://api.zindex.ai | API base URL. Override only for staging or self-hosted. |

Documentation

• Canonical agent front door (with Accept: text/markdown) - the single recommended entry point
• MCP Setup
• Examples - executable workflow recipes (ER from migrations, PR architecture diff, compliance flow, etc.)
• MCP Tools Reference
• Supported Diagram Classes
• API Endpoints

License

MIT