MCP Server

Model Context Protocol Integration

The mindzieAPI MCP server enables AI coding assistants to interact with mindzieStudio programmatically. MCP (Model Context Protocol) provides a standardized way for AI tools to access external capabilities.

Available Tools

The MCP server exposes the following tools for AI assistants:

mindzie_list_block_types

Retrieve information about available block types (filters, calculators, enrichments).

Parameters

Parameter	Type	Required	Description
`category`	String	No	Filter by category: "filters", "calculators", "unified", or omit for filters only

Category Options

Value	Returns
`"filters"`	Filter block types only (default)
`"calculators"`	Calculator block types only
`"unified"`	All block types including enrichments, grouped by category

Example: Get All Block Types (Recommended)

mindzie_list_block_types category="unified"

Returns complete metadata for all block types:

{
  "BlockTypes": [
    {
      "OperatorName": "CaseAttributeFilter",
      "DisplayName": "Case Attribute Filter",
      "Description": "Filter cases based on attribute values",
      "Category": "Attribute Filters",
      "BlockType": "Filter",
      "DocumentationUrl": "/mindzie_studio/filters/case-attribute-filter",
      "UsageFrequency": "High",
      "CommonUseCases": ["Filter by customer segment", "Focus on specific regions"]
    },
    {
      "OperatorName": "CaseDurationCalculator",
      "DisplayName": "Case Duration Calculator",
      "Description": "Calculate the total duration of cases",
      "Category": "Time Calculators",
      "BlockType": "Calculator",
      "DocumentationUrl": "/mindzie_studio/calculators/case-duration-calculator",
      "UsageFrequency": "High",
      "CommonUseCases": ["Analyze cycle times", "Identify slow cases"]
    },
    {
      "OperatorName": "CaseStageCalculator",
      "DisplayName": "Case Stage Calculator",
      "Description": "Assign stage labels to cases based on activity patterns",
      "Category": "Stage Analysis",
      "BlockType": "Enrichment",
      "DocumentationUrl": "/mindzie_studio/enrichments/case-stage-calculator",
      "UsageFrequency": "Medium",
      "CommonUseCases": ["Track case progress", "Monitor stage transitions"]
    }
  ],
  "Categories": ["Attribute Filters", "Time Filters", "Time Calculators", "Stage Analysis"],
  "TotalCount": 45,
  "ByBlockCategory": {
    "Filter": [...],
    "Calculator": [...],
    "Enrichment": [...]
  }
}

Example: Get Filters Only

mindzie_list_block_types category="filters"

Example: Get Calculators Only

mindzie_list_block_types category="calculators"

mindzie_list_projects

List available projects in the current tenant.

Parameters

Parameter	Type	Required	Description
`tenant_id`	String	Yes	The tenant identifier

mindzie_get_project

Get details about a specific project.

Parameters

Parameter	Type	Required	Description
`tenant_id`	String	Yes	The tenant identifier
`project_id`	String	Yes	The project identifier

mindzie_execute_block

Execute a block and return results.

Parameters

Parameter	Type	Required	Description
`tenant_id`	String	Yes	The tenant identifier
`project_id`	String	Yes	The project identifier
`block_id`	String	Yes	The block to execute

mindzie_generate_url

Generate URLs to mindzieStudio pages and entities for navigation or sharing.

Parameters

Parameter	Type	Required	Description
`type`	String	Yes	URL type (see URL Types below)
`entity_id`	String	Conditional	Entity ID for entity-specific pages
`parent_id`	String	Conditional	Parent ID (projectId or notebookId)

URL Types

List Pages (no entity_id required):

Type	parent_id	Description
`projects`	-	Projects list
`apps`	-	Apps list
`investigations`	projectId	Investigations for a project
`dashboards-list`	projectId	Dashboards list for a project
`datasets`	projectId	Datasets for a project
`actions`	projectId	Actions for a project
`bpmn`	projectId	BPMN editor for a project

Entity Pages (entity_id required):

Type	entity_id	parent_id	Description
`dashboard`	dashboardId	-	Single dashboard
`analysis`	notebookId	-	Notebook/analysis page
`block`	blockId	notebookId	Specific block
`enrichment`	enrichmentId	projectId (optional)	Enrichment notebook

Example: Get Dashboard URL

mindzie_generate_url type="dashboard" entity_id="{dashboardId}"

Returns:

{
  "url": "https://host/navigate?type=dashboard&id=...",
  "entityType": "dashboard",
  "entityId": "...",
  "tenantId": "..."
}

Example: Get Block URL

mindzie_generate_url type="block" entity_id="{blockId}" parent_id="{notebookId}"

Example: Get Investigations List URL

mindzie_generate_url type="investigations" parent_id="{projectId}"

Prerequisites

Before setting up the MCP server, ensure you have:

Node.js 18 or later - Download from nodejs.org
A mindzie API token - Generate from your mindzieStudio account settings
Your mindzieStudio instance URL - Either https://www.mindziestudio.com (cloud) or your on-premise URL

Installation

The mindzie MCP server is installed automatically via npx - no manual installation required:

npx -y @mindzie/mcp-server

Environment Variables

Variable	Required	Description
`MINDZIE_API_URL`	Yes	Your mindzieStudio instance URL
`MINDZIE_API_TOKEN`	Yes	Your API authentication token

Setup by Application

Claude Desktop

Claude Desktop is Anthropic's desktop application for Claude AI.

Windows Configuration

Edit the configuration file at:

%APPDATA%\Claude\claude_desktop_config.json

Add the mindzie MCP server:

{
  "mcpServers": {
    "mindzie": {
      "command": "npx",
      "args": ["-y", "@mindzie/mcp-server"],
      "env": {
        "MINDZIE_API_URL": "https://www.mindziestudio.com",
        "MINDZIE_API_TOKEN": "your-api-token-here"
      }
    }
  }
}

macOS Configuration

Edit the configuration file at:

~/Library/Application Support/Claude/claude_desktop_config.json

Add the same configuration as Windows above.

After Configuration

Save the configuration file
Restart Claude Desktop completely (quit and reopen)
Look for the hammer icon in the chat interface - this indicates MCP tools are available

Claude Code (CLI)

Claude Code is Anthropic's command-line interface for Claude AI.

Add the MCP Server

Run this command to register the mindzie MCP server:

claude mcp add mindzie -- npx -y @mindzie/mcp-server

Set Environment Variables

Windows (PowerShell):

$env:MINDZIE_API_URL = "https://www.mindziestudio.com"
$env:MINDZIE_API_TOKEN = "your-api-token-here"

Windows (Command Prompt):

set MINDZIE_API_URL=https://www.mindziestudio.com
set MINDZIE_API_TOKEN=your-api-token-here

macOS/Linux:

export MINDZIE_API_URL="https://www.mindziestudio.com"
export MINDZIE_API_TOKEN="your-api-token-here"

Persistent Configuration

Add the environment variables to your shell profile (.bashrc, .zshrc, or PowerShell profile) for persistence.

Cursor IDE

Cursor is an AI-powered code editor built on VS Code.

Configuration File Location

Create or edit .cursor/mcp.json in your home directory or project root:

{
  "mcpServers": {
    "mindzie": {
      "command": "npx",
      "args": ["-y", "@mindzie/mcp-server"],
      "env": {
        "MINDZIE_API_URL": "https://www.mindziestudio.com",
        "MINDZIE_API_TOKEN": "your-api-token-here"
      }
    }
  }
}

Alternative: Settings UI

Open Cursor
Go to Settings (Ctrl/Cmd + ,)
Search for "MCP"
Click Edit in settings.json
Add the mindzie server configuration

Verify Setup

After configuration, restart Cursor and check that mindzie tools appear in the AI assistant's available tools.

Windsurf (Codeium)

Windsurf is Codeium's AI-powered IDE.

Configuration File Location

Create or edit the MCP configuration file:

Windows:

%USERPROFILE%\.codeium\windsurf\mcp_config.json

macOS/Linux:

~/.codeium/windsurf/mcp_config.json

Configuration

{
  "mcpServers": {
    "mindzie": {
      "command": "npx",
      "args": ["-y", "@mindzie/mcp-server"],
      "env": {
        "MINDZIE_API_URL": "https://www.mindziestudio.com",
        "MINDZIE_API_TOKEN": "your-api-token-here"
      }
    }
  }
}

Verify Setup

Restart Windsurf
Open the Cascade panel
The mindzie tools should be available for process mining queries

VS Code with Continue Extension

Continue is an open-source AI coding assistant for VS Code.

Install Continue

Open VS Code
Go to Extensions (Ctrl/Cmd + Shift + X)
Search for "Continue" and install it

Configure MCP Server

Edit Continue's configuration file:

Windows:

%USERPROFILE%\.continue\config.json

macOS/Linux:

~/.continue/config.json

Add the MCP server to the mcpServers section:

{
  "mcpServers": [
    {
      "name": "mindzie",
      "command": "npx",
      "args": ["-y", "@mindzie/mcp-server"],
      "env": {
        "MINDZIE_API_URL": "https://www.mindziestudio.com",
        "MINDZIE_API_TOKEN": "your-api-token-here"
      }
    }
  ]
}

Verify Setup

Restart VS Code
Open the Continue panel
Type /tools to see available MCP tools including mindzie

Troubleshooting

MCP Server Not Connecting

Verify Node.js installation: Run node --version (must be 18+)
Test the server manually: Run npx -y @mindzie/mcp-server in terminal
Check environment variables: Ensure both MINDZIE_API_URL and MINDZIE_API_TOKEN are set
Restart the application: Close completely and reopen

Authentication Errors

Verify your API token: Tokens may expire or be revoked
Check token permissions: Ensure the token has access to required resources
Verify the URL: Confirm MINDZIE_API_URL points to your correct instance

Tools Not Appearing

Check configuration syntax: Ensure JSON is valid (no trailing commas)
Verify file location: Configuration file must be in the correct path
Check application logs: Look for MCP-related error messages
Restart completely: Some applications cache MCP configurations

Common Configuration Mistakes

Mistake	Solution
Missing `-y` flag in npx args	Add `-y` to skip confirmation: `["-y", "@mindzie/mcp-server"]`
Trailing comma in JSON	Remove trailing commas from JSON objects
Wrong config file location	Double-check the path for your OS
Token contains special characters	Ensure token is properly quoted in JSON

Security Best Practices

Never commit tokens to version control - Use environment variables or secrets managers
Use project-specific tokens - Create separate tokens for different projects
Rotate tokens regularly - Especially for production environments
Restrict token permissions - Only grant access to required resources
Monitor token usage - Review API access logs periodically

Unified Discovery for AI Assistants

The unified category parameter is designed specifically for AI assistants. When an AI needs to understand what analysis capabilities are available, it can make a single MCP call:

mindzie_list_block_types category="unified"

This returns everything the AI needs to:

Understand available capabilities: All filters, calculators, and enrichments
Select appropriate block types: Based on UsageFrequency and CommonUseCases
Link to documentation: Each block type includes DocumentationUrl
Identify relationships: The RelatedBlocks field suggests complementary block types

Example AI Workflow

An AI assistant helping a user analyze process duration might:

Call mindzie_list_block_types category="unified" to discover capabilities
Find block types where CommonUseCases contains "duration"
Suggest the CaseDurationCalculator and WaitTimeCalculator
Create the appropriate blocks using the API
Execute and interpret results

Response Field Reference

When using category="unified", each block type includes:

Field	Description	AI Use
`OperatorName`	Technical identifier	Use when creating blocks via API
`DisplayName`	Human-readable name	Show to users
`Description`	Brief description	Help users understand purpose
`Category`	Functional grouping	Organize suggestions
`BlockType`	Filter/Calculator/Enrichment	Determine usage context
`DocumentationUrl`	Link to docs	Fetch detailed information
`UsageFrequency`	High/Medium/Low	Prioritize common blocks
`CommonUseCases`	Example scenarios	Match to user goals
`RelatedBlocks`	Related block types	Suggest complementary blocks
`UsageNotes`	Additional guidance	Provide context to users

Best Practices

For AI Assistants

Start with unified discovery: Always call with category="unified" first
Cache results: Block type metadata changes infrequently
Match use cases: Use the CommonUseCases field to find relevant blocks
Suggest related blocks: Use RelatedBlocks to offer complementary analysis

For Developers

Secure your tokens: Never expose API tokens in client-side code
Use appropriate scopes: Request only the permissions needed
Handle rate limits: Implement exponential backoff for retries
Validate responses: Check for errors before processing results

Next Steps

Unified Block Types API - Direct API documentation
URL Generation API - Generate navigation URLs
AI Coding Tools Overview - General AI tool integration
Authentication - API authentication details