lucid-mcp/skills/lucid/references/tool-guide.md

Lucid MCP Tool Reference Guide

Full detail on every Lucid MCP tool: what it does, when to use it, example prompts, and edge cases.

---

Tool: Search Documents

Purpose: Full-text search across the user's entire Lucid library (Lucidchart + Lucidspark).

Input: Natural language query describing what to find.

Output: List of matching documents with titles, document types, and direct links.

Example prompts:

• "Find my Birmingham transit architecture diagram"
• "Search for any process flows related to display installation"
• "Do I have a diagram showing the RDMC API integration?"
• "Find last month's standup board"

Edge cases:

• If no results found: ask the user for alternate search terms or whether the document might be in a shared folder
• If many results: list top 5 with titles, ask user to select
• Search may not find content on pages 2+ of a document (known Lucid limitation as of May 2026)

---

Tool: Get Document Content / Summary

Purpose: Retrieve the textual content, shape labels, connections, and structure of a specific Lucid document.

Input: Document ID or URL.

Output: Structured description of document content — shapes, labels, arrows, swim lanes, page titles.

Example prompts:

• "Summarize the key steps in this process diagram: [URL]"
• "What nodes are in the architecture diagram I just found?"
• "List all the shapes and connections in this flowchart"
• "What's the data flow shown in this ER diagram?"

Usage pattern: Typically follows a search — take the document URL from search results and pass it to this tool.

Edge cases:

• Complex diagrams with many pages: summarize page by page, ask user which pages matter
• Diagrams with embedded images or custom shapes: describe layout and label text only
• If content is sparse/empty: report that the document appears blank or contains mostly images

---

Tool: Create Diagram

Purpose: Generate a new Lucid diagram with standard shapes based on a text description.

Input: Structured description including:

• Diagram type (flowchart, sequence, ER, user flow, network, swim lane, etc.)
• Node/shape names and labels
• Connections (which node connects to which, direction, label on arrow if any)
• Any branching/decision logic

Output: Link to newly created Lucidchart document.

Supported diagram types (standard shapes):

• Process flowcharts
• User flow diagrams
• Sequence diagrams
• Entity-relationship (ER) diagrams
• Network / system architecture diagrams
• Swim lane diagrams
• Mind maps
• Org charts (see dedicated org chart tool below)

NOT supported (as of May 2026):

• Custom shape libraries (DFD, AWS, GCP, Azure specific icons) — these require manual editing in Lucidchart
• Custom/branded shape sets

Example prompts:

• "Create a user flow for the display provisioning process in Lucid. Start at 'New Display', show 'Register in RDMC', branch to 'Online Check', and end at 'Deployed'."
• "Build a sequence diagram in Lucid showing the RDMC polling a display every 60 seconds — include the status response."
• "Make a swim lane flowchart in Lucid for our helpdesk escalation: lanes for Customer, L1 Support, and Engineering."
• "Create an ER diagram in Lucid for our display inventory schema: Display, Location, Agency, and ServiceRecord tables."

Before invoking: If the user's description is high-level (e.g., "make a diagram for our deployment process"), ask for the key steps or nodes before generating. This avoids a useless first draft.

---

Tool: Create Org Chart

Purpose: Generate a structured org chart diagram in Lucid from text or CSV data.

Input (text): Natural language description of hierarchy.

• Example: "Create an org chart where Bryan is at the top. Under Bryan are Sarah (Director of Ops) and Mike (Director of Engineering). Under Mike are four engineers: Alex, Jamie, Chris, and Dana."

Input (CSV): Uploaded CSV with at minimum:

• Name column
• Manager/Reports-To column
• Optional: Title, Department, Email

CSV column mapping — confirm before generating:

• Name → person's full name
• Manager → their direct manager's name (blank = top of hierarchy)
• Title → job title (optional but recommended)
• Department → used for grouping/color (optional)

Output: Link to newly created org chart in Lucid.

Example prompts:

• "Build an org chart for MPM where Bryan is CEO. Under Bryan: Sarah (COO), Mike (CTO), and Jess (VP Sales)."
• "Generate an org chart from this CSV file I'm uploading. Name is column A, Manager is column C."
• "Create a department hierarchy for our Engineering team in Lucid."

Edge cases:

• Circular references in CSV (A reports to B, B reports to A): flag and ask user to resolve before generating
• Missing manager names that don't match any Name in the dataset: flag as orphaned nodes
• Very large org charts (50+ people): warn that generation may take longer and the diagram will need layout adjustment in Lucidchart

---

Tool: Share Document

Purpose: Share a Lucid document with a specific person by email.

Input:

• Document ID or URL
• Recipient email address
• Permission level: View, Comment, Edit, or Edit and Share

Output: Confirmation that the share was sent.

Example prompts:

• "Share my 'Installation Process Flow' Lucid doc with sarah@messagepoint.media with edit permissions."
• "Give bryan@messagepoint.media view-only access to the Birmingham architecture diagram."
• "Share this board with my whole team at messagepoint.media — give them comment access."

Permission level guide:

• View: Can see the document, cannot edit or share
• Comment: Can add comments, cannot edit shapes
• Edit: Can modify diagram content
• Edit and Share: Full access including re-sharing with others

Always confirm before executing: "I'll share [document title] with [email] at [permission level]. Confirm?"

---

Tool: Create Share Link

Purpose: Generate a shareable URL to a Lucid document with specified permissions.

Input:

• Document ID or URL
• Link permission type: View, Comment, or Edit

Output: Shareable URL string.

Example prompts:

• "Create a view-only share link for the Project Proposal diagram."
• "Get me a comment-enabled link for this board so stakeholders can leave feedback."
• "Make a shareable link for this flowchart — edit permissions."

Use cases:

• Embedding in emails, Slack messages, or proposals
• Sharing with people who don't have a Lucid account (view links work without login)
• Distributing to external clients or transit agencies

After generating: Offer to send the link via email or copy it into an open document/email draft.

---

Tool: Convert SVG to Diagram (lucid_convert_svg_to_diagram)

Purpose: Convert a complete SVG directly into a new editable Lucidchart document. This is the preferred tool for creating most diagrams — it preserves color, handles custom shapes, and produces higher-fidelity output than the JSON spec path.

When to use:

• Any time a flowchart, process flow, network diagram, architecture diagram, user flow, or ER diagram is needed — generate the SVG, then pass it here verbatim
• Any time Claude has already drawn an SVG (e.g. a visualize widget in chat) and the user wants it editable in Lucid
• Any time custom or branded shapes need to be embedded in a Lucid diagram

When NOT to use:

• Sequence diagrams → use lucid_create_sequence_diagram (PlantUML)
• Org charts → use lucid_create_org_chart
• Diagrams requiring Lucid-native shape types: BPMN pools, UML class blocks, named AWS/GCP/Azure library shapes, lucidCard, tables → use lucid_create_diagram_from_specification

Input:

• title: Document title
• svg: A valid SVG string with <svg> tag, max 256KB. Pass verbatim — do not simplify or rewrite before calling.
• product: "lucidchart" (default) or "lucidspark"

Supported SVG elements: <rect>, <polygon>, <ellipse>, <circle>, <line>, <path>, <text>. These map to Lucid flowchart shapes (process boxes, decision diamonds, terminators, circles) with connecting lines.

Color handling: Colors applied via inline fill and stroke attributes are preserved. Theme classes c-purple, c-teal, c-coral, c-blue, c-green, c-amber, c-red, c-pink, c-gray are also supported.

Custom shape embedding: To include a custom shape (MPM hardware icon, branded element, shape from "My Library"):

1. Ask the user to export/share the SVG source of their custom shape
2. Embed it as a <g transform="translate(x,y)">...</g> block in the diagram SVG
3. Pass the full composed SVG to this tool The custom shape lands in Lucidchart as a fully editable element — same end result as placing it from a shape library.

Custom shape libraries (My Library): NOT accessible via the MCP API. Only AWS 2024, GCP 2021, and Azure 2024 libraries are exposed via get_mcp_resource. The SVG embed approach above is the correct workaround.

Example prompts:

• "Build a display provisioning flowchart and push it to Lucid."
• "Take that SVG diagram you just generated and make it editable in Lucidchart."
• "Create an architecture diagram using our custom Escalator shape — here's the SVG source."
• "Convert this process flow to a Lucid document."

Output: Edit URL and view URL for the new Lucidchart document.

Verified: Smoke-tested 2026-05-21. Colors, shapes, and connections confirmed working.

---

Authentication & Setup Notes

The Lucid MCP server uses OAuth. First-time setup requires:

1. A Lucid account (Team or Enterprise plan)
2. Lucid Admin Panel → Security → Feature Controls → enable "Allow users to connect" under MCP Access
3. In CoWork: open the lucid-mcp plugin → Connectors → connect the Lucid connector (OAuth flow)
4. Authorize Claude to access your Lucid account

If tools return authentication errors, go to CoWork plugin settings → lucid-mcp → Connectors → disconnect and reconnect to re-trigger the OAuth flow.

---

Plan Requirements

Feature	Team Plan	Enterprise Plan
Search, fetch, summarize	✅	✅
Create diagrams (all types)	✅	✅
Export as PNG	✅	✅
Add / edit / delete shapes	✅	✅
Create share links	❌	✅
Share with collaborators by email	❌	✅

The lucid_create_document_share_link and share_document_with_collaborators tools require an Enterprise Lucid plan. On Team plan these return 400/403 errors. Direct the user to share manually from within Lucidchart, or note that upgrading to Enterprise unlocks this capability.

---

Known Limitations (as of May 2026)

• Search may not reliably find content on page 2+ of multi-page documents
• AWS 2024, GCP 2021, and Azure 2024 shape libraries ARE accessible via get_mcp_resource — cloud provider shapes work fine (earlier documentation incorrectly said they were unavailable)
• Custom user shape libraries ("My Library") are NOT accessible via the MCP API — only the three cloud provider libraries above are exposed. Workaround: ask the user to share the SVG source of their custom shape, embed it into the diagram SVG, and push via lucid_convert_svg_to_diagram
• Cannot edit existing diagram content via MCP — only read and create new documents
• Editing/opening Kiro-generated diagrams not supported
• lucid_convert_svg_to_diagram was added to the MCP in May 2026 and is now the preferred diagram creation path for standard flowcharts and structured diagrams