MCP Integration

The ToDiagram MCP (Model Context Protocol) server enables you to generate interactive diagrams from code, AI assistants, internal tools, and developer workflows. Visualize JSON, YAML, XML, and CSV data as editable diagrams directly from your AI copilots like Claude, Cline, or custom agents.

What is MCP?

Model Context Protocol (MCP) is an open protocol that standardizes how AI applications connect to external data sources and tools. It allows AI assistants to interact with various services through a unified interface.

ToDiagram's MCP server provides tools that AI assistants can use to:

• Generate diagrams from various data formats
• Create custom node-and-edge diagrams
• Generate Mermaid flowcharts
• Visualize data structures on demand

Requirements

Prerequisites:

• ToDiagram Pro subscription
• Node.js 16+ or npx installed
• MCP-compatible client (Claude Desktop, Cline, etc.)

Quick Start

npx @todiagram/todiagram-mcp@latest

npm install -g @todiagram/todiagram-mcp

{
  "mcpServers": {
    "todiagram": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "@todiagram/todiagram-mcp@latest"
      ],
      "env": {
        "TODIAGRAM_API_KEY": "your-api-key-here"
      }
    }
  }
}

Using ToDiagram, create a diagram showing a web application 
architecture with load balancer, web servers, and database.

Available Tools

The MCP server provides three main tools that AI assistants can use:

1. Generate Mermaid Diagram

Tool name: generateMermaidDiagram

Creates Mermaid flowchart diagrams from natural language descriptions.

Parameters:

• description (string, required): Natural language description of the diagram
• direction (string, optional): Layout direction - "RIGHT", "LEFT", "TOP", or "DOWN"

Use cases:

• Process flows
• Decision trees
• Sequential workflows
• State machines

Example usage:

Create a Mermaid flowchart showing the user authentication process 
with login, verification, and session creation.

2. Generate Custom Diagram

Tool name: generateCustomDiagram

Creates node-and-edge diagrams with custom properties and relationships.

Parameters:

• description (string, required): Natural language description of the diagram
• direction (string, optional): Layout direction - "RIGHT", "LEFT", "TOP", or "DOWN"

Use cases:

• System architecture
• Network topology
• Entity relationships
• Component interactions
• Microservices architecture

Example usage:

Create a system architecture diagram with API gateway, 
three microservices, and a message queue.

3. Generate Data Diagram

Tool name: generateDataDiagram

Visualizes structured data as diagrams from JSON, YAML, XML, or CSV.

Parameters:

• content (string, required): The data content to visualize
• format (string, required): Format type - "json", "yaml", "xml", or "csv"
• rootName (string, optional): Name for the root node (default: "Root")

Use cases:

• Visualizing configuration files
• Exploring API responses
• Understanding data structures
• Analyzing nested objects

Example usage:

Visualize this JSON data as a diagram: 
{"users": [{"id": 1, "name": "Alice"}, {"id": 2, "name": "Bob"}]}

Supported Formats

Data Formats

The MCP server can visualize the following data formats:

Diagram Types

Configuration

Claude Desktop

Edit claude_desktop_config.json (location varies by OS):

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

Windows: %APPDATA%\Claude\claude_desktop_config.json

Linux: ~/.config/Claude/claude_desktop_config.json

Cline (VS Code Extension)

Edit MCP settings in VS Code:

1. Open VS Code Settings
2. Search for "MCP"
3. Add ToDiagram MCP configuration to Cline settings
4. Restart VS Code

Custom MCP Clients

For custom integrations, connect to the MCP server using the stdio transport:

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

const transport = new StdioClientTransport({
  command: 'npx',
  args: ['-y', '@todiagram/todiagram-mcp@latest'],
  env: {
    TODIAGRAM_API_KEY: process.env.TODIAGRAM_API_KEY
  }
});

const client = new Client({ name: 'my-app', version: '1.0.0' }, {
  capabilities: {}
});

await client.connect(transport);

Response Format

All MCP tools return a diagram URL and metadata:

{
  "url": "https://todiagram.com/editor?id=abc123",
  "documentId": "abc123",
  "format": "custom",
  "message": "Diagram generated successfully"
}

Response fields:

• url: Direct link to view/edit the diagram
• documentId: Unique identifier for the diagram
• format: Format type (json, yaml, xml, csv, custom, mermaid)
• message: Success or error message

Use Cases

1. AI-Assisted Architecture Design

Use AI assistants to quickly generate system architecture diagrams:

Create a microservices architecture with:
- API Gateway
- User Service
- Order Service
- Payment Service
- PostgreSQL database
- Redis cache
Show connections between services

2. Configuration Visualization

Visualize complex configuration files:

Visualize this Kubernetes deployment YAML as a diagram:
[paste YAML content]

3. API Response Exploration

Explore API responses interactively:

Show this API response as a diagram so I can understand its structure:
[paste JSON response]

4. Documentation Generation

Generate diagrams for technical documentation:

Create a flowchart showing the CI/CD pipeline:
code commit → tests → build → staging → production

5. Code to Diagram

Convert code structures to visual diagrams:

Create a diagram from this data structure:
[paste code snippet]

Best Practices

Writing Effective Prompts

Be Specific:

❌ "Create a diagram"
✅ "Create a system architecture diagram with load balancer, 
   3 web servers, API gateway, and PostgreSQL database"

Mention Relationships:

❌ "Show User and Order services"
✅ "Show User service connects to Order service via REST API"

Specify Layout:

✅ "Create a horizontal flowchart (left to right) showing..."
✅ "Create a vertical diagram (top to bottom) with..."

Security

1. Protect API Keys: Never commit keys to git or share publicly
2. Rotate Regularly: Generate new keys periodically
3. Revoke Unused Keys: Delete keys you're no longer using
4. Use Environment Variables: Store keys in env vars, not config files
5. Monitor Usage: Check API usage in account settings

Performance Tips

1. Keep Descriptions Focused: Simpler descriptions generate faster
2. Use Appropriate Format: Choose the right diagram type for your data
3. Limit Node Count: Large diagrams (100+ nodes) may be slow
4. Batch Operations: Generate multiple simple diagrams rather than one complex one

Troubleshooting

Examples

Example 1: Microservices Architecture

Prompt:

Create a microservices diagram showing:
- Frontend (React)
- API Gateway (Kong)
- Auth Service (connects to Auth Gateway)
- User Service (connects to API Gateway)
- Order Service (connects to API Gateway and User Service)
- Payment Service (connects to Order Service)
- PostgreSQL (connects to all services)
- Redis Cache (connects to User Service)
Layout: horizontal (left to right)

Example 2: CI/CD Pipeline

Prompt:

Create a Mermaid flowchart for CI/CD:
1. Developer pushes code
2. GitHub triggers webhook
3. Run unit tests
4. If tests pass → Build Docker image
5. If tests fail → Notify developer
6. Push image to registry
7. Deploy to staging
8. Run integration tests
9. If pass → Deploy to production
10. If fail → Rollback

Example 3: Data Structure Visualization

Prompt:

Visualize this JSON as a diagram:
{
  "company": "TechCorp",
  "departments": [
    {
      "name": "Engineering",
      "employees": 50,
      "teams": ["Backend", "Frontend", "DevOps"]
    },
    {
      "name": "Sales",
      "employees": 20,
      "teams": ["Enterprise", "SMB"]
    }
  ]
}

Additional Resources

• NPM Package: npmjs.com/package/@todiagram/todiagram-mcp
• MCP Documentation: modelcontextprotocol.io
• Claude Desktop Setup: docs.anthropic.com/claude/docs/mcp
• API Documentation: See REST API section
• Support: Contact support via todiagram.com

Next Steps

• Generate your first diagram with AI assistance
• Explore Data Formats to understand visualization options
• Learn about Custom Diagrams for advanced use cases
• Check REST API for programmatic access