MCP Tools

Zindex exposes 8 tools via the Model Context Protocol. Agents discover these automatically when the MCP server is configured.

Building an agent integration? See How AI Agents Should Use Zindex for the recommended tool usage pattern, scene lifecycle, and conflict recovery behavior.

Tool input families

The 8 tools fall into four input patterns:

• Scene document tools - dsp_create_scene, dsp_validate_scene, dsp_normalize_scene take a full scene document with schemaVersion, scene, and elements.
• Scene ID tools - dsp_get_scene, dsp_render_scene take a sceneId to reference a persisted scene.
• Operations tool - dsp_apply_ops takes a sceneId, baseRevision, ops array, and optional message.
• Revision tools - dsp_diff_scene, dsp_list_revisions take a sceneId and revision numbers.

Supported render formats: svg, png.

dsp_create_scene

Create a new diagram scene.

Input:

{
  "scene": {
    "schemaVersion": "0.1",
    "scene": {
      "id": "my-diagram",
      "title": "Architecture",
      "units": "px",
      "canvas": { "width": 1200, "height": 800, "background": "#ffffff" }
    },
    "elements": []
  }
}

Output:

{ "sceneId": "my-diagram", "revision": 1 }

Always declare scene-level diagramFamily (architecture, workflow, entityRelationship, sequence, network, orgchart, or uiflow) - it gates family-specific node and edge types, validation, and rendering behaviour, and omitting it triggers a MISSING_DIAGRAM_FAMILY info diagnostic. For automatic positioning, include layoutStrategy. To add icons to nodes, set "icon": "lucide:database" (or any key from the built-in icon registry).

dsp_apply_ops

Apply operations to an existing scene. Supports 17 operation types.

Input:

{
  "sceneId": "my-diagram",
  "baseRevision": 1,
  "transactionMode": "allOrNothing",
  "ops": [
    {
      "op": "createNode",
      "id": "api",
      "nodeType": "service",
      "shape": "roundedRect",
      "label": "API Gateway",
      "layout": { "mode": "absolute", "x": 100, "y": 100, "width": 200, "height": 80 }
    },
    {
      "op": "createNode",
      "id": "db",
      "nodeType": "database",
      "shape": "cylinder",
      "label": "PostgreSQL",
      "layout": { "mode": "absolute", "x": 400, "y": 100, "width": 160, "height": 90 }
    },
    {
      "op": "createEdge",
      "id": "e1",
      "from": { "elementId": "api" },
      "to": { "elementId": "db" },
      "router": "orthogonal",
      "label": "queries"
    }
  ]
}

Output:

{
  "applied": true,
  "revision": 2,
  "changedElementIds": ["api", "db", "e1"],
  "diagnostics": []
}

Returns 409 if baseRevision doesn’t match the current revision.

dsp_get_scene

Retrieve a scene by ID, optionally at a specific revision.

Input:

{ "sceneId": "my-diagram", "revision": 1 }

Output:

{
  "sceneId": "my-diagram",
  "revision": 2,
  "scene": { "schemaVersion": "0.1", "scene": { ... }, "elements": [ ... ] }
}

dsp_validate_scene

Validate a scene document for structural and semantic correctness without persisting it.

Input:

{
  "scene": {
    "schemaVersion": "0.1",
    "scene": { "id": "test", "units": "px", "canvas": { "width": 800, "height": 600 } },
    "elements": [
      { "id": "n1", "kind": "node", "nodeType": "service", "shape": "rect", "label": "API" }
    ]
  }
}

Output (valid):

{ "ok": true, "diagnostics": [] }

Output (invalid):

{
  "ok": false,
  "diagnostics": [
    { "severity": "error", "code": "DUPLICATE_ID", "message": "Duplicate element ID: n1" }
  ]
}

dsp_normalize_scene

Normalize a scene - apply defaults, resolve layout, and compute element positions. Returns the fully normalized scene without persisting.

Input:

{
  "scene": {
    "schemaVersion": "0.1",
    "scene": { "id": "test", "units": "px", "canvas": { "width": 800, "height": 600 } },
    "elements": [
      { "id": "n1", "kind": "node", "nodeType": "service", "shape": "rect", "label": "API",
        "layout": { "mode": "absolute", "x": 50, "y": 50, "width": 200, "height": 80 } }
    ]
  }
}

Output: The full normalized scene with computed field containing resolved bounds and edge paths.

dsp_render_scene

Render a previously created scene to SVG or PNG.

Input:

{ "sceneId": "my-diagram", "format": "svg" }

Output (SVG):

{ "mimeType": "image/svg+xml", "content": "<svg>...</svg>" }

Output (PNG):

{ "mimeType": "image/png", "content": "<base64-encoded>" }

Pass "theme" to control render aesthetics: "clean" (default), "dark", "blueprint", "sketch".

dsp_diff_scene

Compare two revisions of a scene. Returns categorized changes (added, removed, modified elements).

Input:

{
  "sceneId": "my-diagram",
  "from": 1,
  "to": 3
}

to is optional - defaults to the current revision.

Output:

{
  "sceneId": "my-diagram",
  "fromRevision": 1,
  "toRevision": 3,
  "summary": { "added": 2, "removed": 1, "modified": 1 },
  "added": ["node-x", "edge-y"],
  "removed": ["node-old"],
  "modified": ["node-a"],
  "changedConstraintIds": []
}

dsp_list_revisions

List all revisions of a scene with timestamps, messages, and change summaries.

Input:

{
  "sceneId": "my-diagram"
}

Output:

{
  "sceneId": "my-diagram",
  "currentRevision": 3,
  "revisions": [
    { "revision": 3, "createdAt": "2026-04-01T12:00:00Z", "message": "Added cache layer", "summary": { "added": 1, "removed": 0, "modified": 1 } },
    { "revision": 2, "createdAt": "2026-04-01T11:30:00Z", "message": "Initial structure", "summary": { "added": 5, "removed": 0, "modified": 0 } },
    { "revision": 1, "createdAt": "2026-04-01T11:00:00Z", "message": null, "summary": null }
  ]
}

Configuration

The MCP server is a thin HTTP client to the Zindex API. Every tool call routes through api.zindex.ai, so scenes are persisted in the cloud and you get revision history, multi-session sceneId references, and visual diff out of the box.

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

Environment variables

If ZINDEX_API_KEY is missing, the server exits with a setup message pointing at /docs/getting-started/mcp-setup/. npx @zindex-ai/mcp --help and --version work without a key.