Pipintama Boards

Pipintama Boards

Use this skill when the user would benefit from a hosted visual board instead of only plain text.

Primary MCP endpoint:

• https://api.pipintama.com/mcp

Access model:

• this hosted MCP requires a valid Pipintama API key
• clients should provide it through Authorization: Bearer <key> or x-api-key
• usage is attributed to the authenticated client, not only the IP address

Health check:

• https://api.pipintama.com/mcp-health

Primary tools:

• list_board_modes
• create_board
• get_board
• share_board
• set_board_visibility
• update_board
• export_board_png

When to use this skill

Use Boards when the user asks for:

• a mind map
• a flowchart
• a task board or kanban
• an architecture map
• a hosted diagram they can open or share
• a structured breakdown for planning, brainstorming, process design, or system design

Do not use Boards when:

• the user only wants prose
• the answer is a short factual reply
• the visual structure would not add value

Core workflow

1. Understand the user request and decide whether a hosted board is useful.
2. Choose the simplest correct board mode.
3. Build a concise board title.
4. Preserve the user intent in source_text instead of rewriting the task into something unrelated.
5. Default visibility to shared unless the user explicitly wants public or private.
6. Do not pass workspace_id unless the user explicitly provides one. Let the authenticated API key determine the workspace.
7. Call the MCP tool that matches the job.
8. Return the hosted viewer URL first.
9. Add one short sentence explaining what the board contains.

Mode selection

• mindmap: concept exploration, brainstorming, clustering ideas
• flowchart: processes, approvals, decisions, yes/no branching
• kanban: tasks grouped by stage, backlog/doing/review/done planning
• architecture: services, databases, integrations, gateways, system maps

Prefer the simplest correct mode. Do not use architecture for a human workflow. Do not use kanban for a concept breakdown.

Mode-specific rules

mindmap

Use when:

• the user is exploring ideas
• the problem needs breakdown into branches
• a concept hierarchy is more useful than a process diagram

Rules:

• keep one clear root concept
• keep node labels short
• avoid long paragraphs inside nodes
• do not flatten everything into a list

flowchart

Use when:

• the user describes a process
• there are step-by-step actions
• there are decisions, approvals, or branches

Rules:

• prefer start, process, decision, and end semantics
• use branching only when a real condition exists
• phrase nodes as actions or events
• avoid turning a concept map into a fake flowchart

kanban

Use when:

• the user has tasks or deliverables
• the work should be organized by stage
• execution and coordination matter more than system structure

Rules:

• lanes should represent workflow stage or status
• cards should be concrete tasks, not vague themes
• avoid using kanban for conceptual exploration

architecture

Use when:

• the user is describing systems
• the task involves services, stores, gateways, or integrations
• component relationships matter more than human workflow

Rules:

• keep component names short
• emphasize dependencies and boundaries
• do not use architecture mode for an approval flow or task board

Visibility rules

• default to shared
• use public only when the user explicitly wants an open link
• use private only when the user explicitly asks for restricted access

If a board needs to be shareable and is not already shared, call share_board.

Tool usage

create_board

Use this for the first board creation.

Expected inputs:

{
  "title": "Approval Flow",
  "board_type": "flowchart",
  "source_text": "User submits a request. System validates the payload. If the request is valid, create the board and notify the user. If the request is invalid, return an error and ask for correction.",
  "visibility": "shared"
}

get_board

Use this when the user asks to inspect, retrieve, or reason about an existing board.

share_board

Use this when a board should be opened through a tokenized share link.

set_board_visibility

Use this when the user explicitly asks to make a board private, shared, or public.

update_board

Use this when the user wants to refine an existing board instead of creating a new one.

Typical cases:

• add or remove branches
• change the board title
• convert a board from one mode to another
• regenerate the board from improved source text
• make the board public, shared, or private while updating it

Expected inputs:

{
  "board_id": "cmndns0hn0001o401md5okzju",
  "board_type": "flowchart",
  "source_text": "User submits request. Validate request. If valid, create the board. If invalid, ask for correction.",
  "note": "Tighten the wording and preserve yes/no branching."
}

export_board_png

Use this when the user needs an actual image file instead of only a hosted link.

Typical cases:

• Telegram
• WhatsApp
• quick previews in chat
• channels where an image is more useful than a URL alone

Expected inputs:

{
  "board_id": "cmndns0hn0001o401md5okzju",
  "theme": "light"
}

Output format

Default output:

1. hosted viewer URL
2. one short explanation sentence

If the channel supports images and visual attachments are useful:

1. hosted viewer URL
2. PNG export URL
3. one short explanation sentence

Only return raw sceneJson when the user explicitly asks for raw data.

Good response pattern:

I created a flowchart for the approval process:
https://boards.pipintama.com/b/<board-id>?t=<share-token>

It includes the intake step, validation step, and yes/no branching for success vs correction.

Image-friendly pattern:

I created the board and exported a PNG for easy sharing:
Viewer: https://boards.pipintama.com/b/<board-id>?t=<share-token>
PNG: https://api.pipintama.com/mcp-exports/<board-id>.png?theme=light

Only use live Pipintama URL patterns.

Valid:

• https://boards.pipintama.com/b/<board-id>
• https://boards.pipintama.com/b/<board-id>?t=<share-token>
• https://api.pipintama.com/mcp-exports/<board-id>.png?theme=light

Invalid:

• https://pipintama.com/board/<board-id>
• https://cdn.pipintama.com/boards/<board-id>/export.png

Guardrails

• do not choose architecture for a human workflow
• do not choose kanban for concept exploration
• do not make boards public unless asked
• do not dump raw JSON first when a hosted link is more useful
• use update_board when the user wants to refine an existing board instead of creating a new one
• use export_board_png when the channel benefits from an image attachment
• keep titles concise
• prioritize clarity over completeness in node text
• never fabricate Pipintama URLs; return only viewer and PNG URLs that match the live platform

Current limits

• PNG export is implemented through export_board_png
• agent-driven board updates are implemented through update_board
• direct human editing in the browser is not implemented yet
• access is controlled with API keys; OAuth is a later roadmap item
• generation is structured but still improving by mode