Skip to main content
Glama

Convyy MCP

A standalone stdio MCP server that lets an AI agent (Codex, Claude, Cursor, Cline, etc.) work with an already open Convyy board: draw on the canvas, apply templates, manage pages, read content, and revert its own actions.


1. What this is

Convyy MCP is a bridge between an AI agent and a live Convyy board. The agent doesn't just produce text — it calls tools, and the result appears on the canvas.

Core principle: the model owns the content and the structure, the server owns layout and style. The server never invents content from a fixed template — it lays out exactly what the agent sends and styles it to match the board.

How it works

By default the server starts in relay mode:

  1. the MCP client (Codex/Claude) talks to convyy-mcp over stdio;

  2. convyy-mcp exposes its tools immediately via tools/list;

  3. the Convyy board open in the browser connects to the local relay at http://127.0.0.1:4318;

  4. tool calls are forwarded into the board runtime and committed onto the canvas.

To actually draw anything you need both halves: an open board in the browser and Convyy MCP connected in the agent. The --local flag is for debugging only.

Note: these are MCP tools, not slash commands. The correct protocol is initialize → tools/list → tools/call. Don't type /convyy_draw into the client's input box.


Related MCP server: Overboard Studio MCP Server

2. Installation

git clone https://github.com/divulture/convyy-mcp.git
cd convyy-mcp
npm install
npm run build

Verify the build:

npm run typecheck   # types
npm run test        # unit tests
npm run smoke       # stdio boot/handshake check

npm run smoke confirms the server starts and answers the handshake. It does not prove that the browser board is already attached to the relay.

After building, two binaries are available:

  • convyy-mcpdist/server.js (the MCP server);

  • convyy-mcp-devdist/dev/devRelayCli.js (dev relay CLI).


3. Connecting it to your agent

Connect it like any other stdio MCP server. Point it at dist/server.js or the convyy-mcp binary.

Claude (Desktop / Claude Code)

Claude Code (CLI):

claude mcp add convyy -- node /absolute/path/convyy-mcp/dist/server.js

Or manually in claude_desktop_config.json (Claude Desktop):

{
  "mcpServers": {
    "convyy": {
      "command": "node",
      "args": ["/absolute/path/convyy-mcp/dist/server.js"]
    }
  }
}

Codex

In ~/.codex/config.toml:

[mcp_servers.convyy]
command = "node"
args = ["/absolute/path/convyy-mcp/dist/server.js"]

If the binary is on your PATH

If the package is installed globally or linked (npm link), it's simpler:

{
  "mcpServers": {
    "convyy": { "command": "convyy-mcp", "args": [] }
  }
}

After connecting

  1. restart/reconnect the MCP client;

  2. confirm tools/list exposes the convyy_* tools;

  3. open a Convyy board in the browser and check the relay reaches healthy;

  4. give the agent a task — the result appears on the canvas.


4. Available tools

Five tools with clear boundaries: four write tools (draw, apply_template, pages, revert) and one read tool (analyze).

convyy_draw — draw anything

The universal tool. The agent sends an array of elements built from native board primitives; the server lays them out as canvas objects.

Supported elements:

  • shape — a shape (process, decision, terminator, rectangle, ellipse… the flowchart set);

  • sticky — a sticky note (with a colour);

  • frame — a container frame;

  • text — a text block;

  • connector — a link between elements (from/to by id).

An optional layout hint (free | flow-lr | grid) lets the agent skip coordinates and have the server place elements. This is the escape hatch for anything that doesn't fit a template (custom diagrams, sticky sets, flows, summaries).

convyy_apply_template — adaptive named template

Recurring business artefacts with a tuned layout and style. The agent provides a templateId and a structure (lanes and stages of any size); the server builds the grid and grows it to fit the content, inheriting the preset style. Content is never truncated.

Available templateIds:

  • cjm — customer journey map (default lanes: actions/pains/opportunities; add your own);

  • swot — SWOT analysis;

  • raci — RACI matrix (roles × tasks);

  • retro — retrospective board;

  • bmc — Business Model Canvas;

  • kanban — kanban board (rendered as a native kanban frame).

Calling with { "list": true } returns the available templates and their structure shape without committing anything.

convyy_pages — page management

action:

  • list — pages + active page + session binding;

  • create — create a page (name) and make it active;

  • switch — switch to a page (pageId).

convyy_analyze — read the canvas (read-only)

scope:

  • image — analyze the images on the page;

  • page — text summary of the whole page;

  • selection — summary of the selection (falls back to the whole page if unavailable).

Returns a text summary and changes nothing on the board.

convyy_revert — undo

Reverts the last AI batch of the current session. A safety tool.


Example prompts

  • "Draw an auth flow diagram with a branch" → convyy_draw

  • "Build an onboarding CJM with 6 stages and an emotions lane" → convyy_apply_template (cjm)

  • "Launch kanban: Backlog / Doing / Review / Done" → convyy_apply_template (kanban)

  • "Drop 5 sticky notes about risks" → convyy_draw

  • "What's on this page right now?" → convyy_analyze (page)

  • "Undo that" → convyy_revert


Constraints (MVP)

  • the agent does not edit existing user objects — it only adds new AI-owned content;

  • every response is committed as a separate batch;

  • undo only works for the last AI batch of the current session;

  • native tables and images in convyy_draw are not supported yet (backlog) — grid-style tables are assembled from shape elements.


Architecture

The public surface (what the model sees in tools/list) is owned by the server catalog. Rendering to the board goes through the internal commit engine (runPromptcommitBatch) — which is no longer a public tool. The agent names a content tool directly (convyy_draw / convyy_apply_template) and the server resolves the page and commits the batch.

src/
  application/    # orchestration: runPrompt (internal commit engine), pages, analyze
  contracts/      # tool, session and host-adapter types
  orchestration/  # tool registry, follow-up actions, session machine
  runtime/        # runtime state (session ↔ page bindings)
  server/         # stdio transport, JSON-RPC, tool catalog
  tools/          # drawTool, templateTool, templatePresets
tests/

Commands

npm install
npm run build
npm run smoke
npm run typecheck
npm run test

Troubleshooting (relay)

If tools/list exposes the tools but nothing shows up on the board, the problem is the board↔relay link, not MCP registration:

  1. the board's relay diagnostics panel is open and not disabled;

  2. it reached healthy (instead of getting stuck in connecting/failing);

  3. the local relay is listening on 127.0.0.1:4318;

  4. the server was started without --local.

An error like Unknown command: /convyy_draw only means a tool was called as a slash command — it's not a server failure. Tools are invoked through tools/call.

Available Tools

5 tools
convyy_analyzeAnalyze CanvasA

Read the canvas and return a text summary. Scope: image (images on the page), page (the whole page), or selection. Does not modify the board.

ParametersJSON Schema
NameRequiredDescriptionDefault
scopeYes
pageIdNo
boardIdNo
sessionIdNo

TDQS

A3.6/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full burden. It correctly states the tool does not modify the board, but does not disclose other behavioral traits such as performance, limits, or what happens when scope='selection' and no selection exists. The description is minimally transparent.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two sentences long, with the purpose front-loaded. Every word earns its place. No redundancy or fluff.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Despite having 4 parameters and no output schema, the description does not explain the format or content of the returned 'text summary', nor does it specify what happens when optional parameters are omitted. This is a significant gap for an analysis tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must compensate. It adds meaning for the 'scope' parameter by explaining each enum value, but provides no context for pageId, boardId, or sessionId. This partial coverage justifies a score of 3.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the verb 'Read' and resource 'canvas', and specifies the scope options (image, page, selection) that distinguish it from sibling tools like convyy_draw or convyy_apply_template which modify the board.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage is for reading only ('Does not modify the board') but provides no explicit guidance on when to use this tool versus siblings like convyy_pages or convyy_draw. No alternative names or exclusions are mentioned.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

convyy_apply_templateApply TemplateA

Apply a named, adaptive template (cjm, swot, raci, retro, bmc, kanban). You provide the structure (lanes and stages of any size); the server owns the layout and inherits the preset style. The grid grows to fit your content. Call with { list: true } to see available templates and their structure.

ParametersJSON Schema
NameRequiredDescriptionDefault
listNoReturn the available templates instead of rendering.
promptYesShort description (used for kanban frame title and fallback).
overridesNoOptional: { addLane:[{id,label}], addColumn:[{id,title}] } to extend the grid on the fly.
structureNoGrid templates: { lanes:[{id,label,color?}], stages:[{id,title,cells:{laneId:text}}] }. Kanban: { columns:[{id,title,order}], cards:[{id,title,columnId,status,order}] }.
templateIdNocjm | swot | raci | retro | bmc | kanban

TDQS

A4.2/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations exist, so the description carries full burden. It discloses key behaviors: the server owns the layout, inherits preset style, grid grows to fit content, and the user provides structure. It lacks detail on side effects (e.g., overwrite behavior) but covers the main behavioral traits.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is three sentences with clear front-loading: first defines purpose, second explains the user/server division, third gives a specific usage hint. No wasted words; every sentence earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given 5 parameters including nested objects and no output schema, the description covers the core workflow well. It explains the list discovery mechanism and the flexible structure input. However, it does not describe what the tool returns after applying a template (e.g., success message, ID), which is a minor gap.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so baseline is 3. The description adds value beyond schema by explaining the 'list' parameter's purpose (discover templates) and the 'structure' parameter's role ('you provide the structure'). It also lists template names while schema already provides enum, but the context of 'adaptive' templates enriches meaning.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description starts with a specific verb ('Apply') and resource ('named, adaptive template'), listing concrete template IDs (cjm, swot, etc.). It clearly distinguishes the tool from siblings like convyy_analyze or convyy_draw by focusing on template application.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies when to use the tool (to apply a template) and mentions calling with {list:true} to see available templates, but it does not provide explicit when-not-to-use guidance or compare to sibling tools (e.g., when to use convyy_draw instead).

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

convyy_drawDraw On BoardA

Render any board content you compose from native primitives. Provide elements (shape, sticky, frame, text, connector); the server owns ids and styling, but YOU own the layout — give explicit x/y/width/height so nothing overlaps. LAYOUT RULES: (1) Stickies are ALWAYS square; the side equals the width you send (height is ignored), so reserve a square footprint and leave >=40px gaps between boxes. (2) Lay diagrams out on a clean grid (left-to-right or top-to-bottom) and connect adjacent boxes; do NOT place any shape on the straight line between two boxes you connect, or the arrow will cross it. (3) For a branch/decision, offset the branch target to the side or below with clear space so its connector has an empty corridor — the server routes arrows from the nearest edges with elbow bends, which only stays clean when you leave room. Use this for anything that does not fit a named template. THINKING SIGNAL: when you START handling the user's request, call this once with empty elements: [] so the board shows your cursor 'thinking'; then call it again with the real elements once you have composed the answer.

ParametersJSON Schema
NameRequiredDescriptionDefault
layoutNoLayout hint: free | flow-lr | grid. Default free.
promptYesShort description of what to draw.
elementsNoElements you generate from the request. Each is one of: { kind:'shape', id, text, shapeType, x?,y?,width?,height?, fill? } — fill is one of: transparent | white | ink | amber | emerald | sky | violet | rose. | { kind:'sticky', id, text, color?, x?,y?,width?,height? } — color is one of: amber | sky | emerald | rose | violet | orange (default amber). Use these tokens, NOT plain color names like yellow/blue/green. | { kind:'frame', id, title, x?,y?,width?,height? } | { kind:'text', id, text, x?,y?,width?,height?, fontSize?, bold? } | { kind:'connector', from, to, label? }. Omit coordinates to let the server lay them out.

TDQS

A4.9/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations provided, but the description comprehensively explains server ownership of ids/styling, user ownership of layout, sticky square rule, arrow routing, and thinking signal behavior.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is long but efficiently structured: purpose first, then rules, then usage note. Every sentence adds necessary value without redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Covers drawing and layout thoroughly, though lacks explicit return value or error handling. Given no output schema, it's nearly complete for the tool's purpose.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema covers 100% of parameters, but the description adds extensive meaning with element type details, color tokens, layout rules, and usage instructions beyond basic schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool renders board content from primitives and distinguishes it from named templates, specifying it's for anything that doesn't fit a template.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly states when to use (anything not fitting a named template) and provides a thinking signal for initial empty call, plus detailed layout rules.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

convyy_pagesPagesB

Manage board pages: list available pages, create a new one, or switch the active page. Returns pages, the active page id and the current session binding.

ParametersJSON Schema
NameRequiredDescriptionDefault
nameNoPage name for action 'create'.
actionYes
pageIdNoTarget page id for action 'switch'.
boardIdNo
sessionIdNo

TDQS

B3.2/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description must carry full weight. It mentions 'switch the active page' implying mutation, but lacks detail on side effects, permissions, or boundaries. The return data is noted, but behavioral traits are insufficiently disclosed.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two concise sentences with clear action enumeration and return description. No filler, but could list parameters more explicitly.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The tool has 5 parameters and 3 actions, with no output schema. The description vaguely states return values but omits boardId and does not detail action-specific behavior or parameter dependencies. Barely adequate given the complexity.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 40% (only name and pageId have descriptions). The description adds context by mentioning 'active page id' and 'session binding', aiding understanding of pageId and sessionId, but boardId remains unexplained. Partially compensates for low schema coverage.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description specifies the tool manages board pages with three explicit actions (list, create, switch) and states the return values. This differentiates it from sibling tools like convyy_draw or convyy_analyze, but the verb 'Manage' is somewhat generic.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage through the action enum, but provides no explicit guidance on when to choose this tool over siblings or any prerequisites. It tells what the tool does but not when to use it.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

convyy_revertRevert Last BatchB

Revert the last AI batch of the active runtime session.

ParametersJSON Schema
NameRequiredDescriptionDefault
boardIdNo
sessionIdNo

TDQS

B3/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden of behavioral disclosure. However, it only states 'revert' without explaining what happens to the reverted data, whether the action is destructive, or if it has any side effects.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single sentence that is concise and front-loaded, but it could be slightly more efficient by omitting redundant phrasing like 'of the active runtime session' if that is implicit.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the lack of annotations, output schema, and parameter descriptions, the description is too sparse. It does not explain what constitutes an 'AI batch', what 'revert' entails, or how to determine which session is active, making it incomplete for safe and correct use.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema has two parameters (boardId, sessionId) with 0% description coverage, and the description provides no additional meaning for these parameters, leaving the agent without guidance on what values to provide.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action ('revert'), the specific resource ('last AI batch'), and the context ('active runtime session'). This makes the tool's purpose distinct from siblings like convvy_analyze or convvy_draw.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage for undoing the last AI batch but provides no explicit guidance on when to use this tool versus alternatives, nor any exclusions or prerequisites.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 5 tool updatesv0.1.0
    • First observedconvyy_analyze
    • First observedconvyy_apply_template
    • First observedconvyy_draw
    • First observedconvyy_pages
    • First observedconvyy_revert

TDQS

A3.7/5.0

Scored across 5 tools

Disambiguation5/5

Each tool has a clearly distinct purpose: analyze reads content, apply_template applies templates, draw creates custom elements, pages manages board pages, and revert undoes changes. No overlap in functionality.

Naming Consistency4/5

Tool names follow a 'convyy_' prefix with descriptive verbs (analyze, apply_template, draw, revert), but 'pages' is a noun rather than a verb, causing minor inconsistency.

Tool Count5/5

Five tools cover core board operations without being excessive. The number is well-suited for a board management MCP server.

Completeness3/5

The server provides creation (draw, apply_template) and reading (analyze, pages) but lacks tools to modify or delete specific elements. The revert tool only undoes the last batch, which is insufficient for granular edits.

Maintenance

ActivityInactive
ResponsivenessNo issues

Related MCP Connectors

Related MCP Servers

  • A
    license
    Not graded
    quality
    D
    maintenance
    Create visual whiteboards, diagrams, flowcharts, and project plans from AI conversations. 17 MCP tools for board management, element creation, and real-time collaboration.
    1
    MIT
  • A
    license
    Not graded
    quality
    B
    maintenance
    Enables AI agents to create and manipulate live visual diagrams on an Excalidraw canvas in real-time via MCP tools.
    2,420 npm
    38 PyPI
    14
    BSD 3-Clause
  • A
    license
    Not graded
    quality
    D
    maintenance
    Enables AI agents to create, modify, and share diagrams on a live Excalidraw canvas through MCP tools, supporting shapes, text, arrows, batch operations, and export to shareable links with images.
    1,608 npm
    8
    MIT