Convyy MCP
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Convyy MCPCreate a kanban board for launch prep"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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:
the MCP client (Codex/Claude) talks to
convyy-mcpover stdio;convyy-mcpexposes its tools immediately viatools/list;the Convyy board open in the browser connects to the local relay at
http://127.0.0.1:4318;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 buildVerify the build:
npm run typecheck # types
npm run test # unit tests
npm run smoke # stdio boot/handshake checknpm 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-mcp→dist/server.js(the MCP server);convyy-mcp-dev→dist/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.jsOr 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
restart/reconnect the MCP client;
confirm
tools/listexposes theconvyy_*tools;open a Convyy board in the browser and check the relay reaches
healthy;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/toby 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_draware not supported yet (backlog) — grid-style tables are assembled fromshapeelements.
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 (runPrompt → commitBatch) —
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 testTroubleshooting (relay)
If tools/list exposes the tools but nothing shows up on the board, the problem is the
board↔relay link, not MCP registration:
the board's relay diagnostics panel is open and not
disabled;it reached
healthy(instead of getting stuck inconnecting/failing);the local relay is listening on
127.0.0.1:4318;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 toolsconvyy_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.
| Name | Required | Description | Default |
|---|---|---|---|
| scope | Yes | ||
| pageId | No | ||
| boardId | No | ||
| sessionId | No |
TDQS
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.
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.
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.
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.
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.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| list | No | Return the available templates instead of rendering. | |
| prompt | Yes | Short description (used for kanban frame title and fallback). | |
| overrides | No | Optional: { addLane:[{id,label}], addColumn:[{id,title}] } to extend the grid on the fly. | |
| structure | No | Grid templates: { lanes:[{id,label,color?}], stages:[{id,title,cells:{laneId:text}}] }. Kanban: { columns:[{id,title,order}], cards:[{id,title,columnId,status,order}] }. | |
| templateId | No | cjm | swot | raci | retro | bmc | kanban |
TDQS
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.
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.
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.
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.
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.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| layout | No | Layout hint: free | flow-lr | grid. Default free. | |
| prompt | Yes | Short description of what to draw. | |
| elements | No | Elements 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
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.
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.
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.
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.
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.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| name | No | Page name for action 'create'. | |
| action | Yes | ||
| pageId | No | Target page id for action 'switch'. | |
| boardId | No | ||
| sessionId | No |
TDQS
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.
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.
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.
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.
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.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| boardId | No | ||
| sessionId | No |
TDQS
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.
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.
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.
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.
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.
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.
5 tool updates
v0.1.0- First observed
convyy_analyze - First observed
convyy_apply_template - First observed
convyy_draw - First observed
convyy_pages - First observed
convyy_revert
TDQS
Scored across 5 tools
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.
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.
Five tools cover core board operations without being excessive. The number is well-suited for a board management MCP server.
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
Related MCP Connectors
AI agents use CalmBoard MCP to access board data, tasks, insights, and project workflows.
Create, read and live-edit visual boards, Kanban plans, Gantt timelines and diagrams with AI agents.
Create and manage Mermaid.js flowcharts and diagrams with AI agents via MCP.
Remote MCP for Kanban AI boards—manage projects, tasks, and comments from AI tools.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceCreate visual whiteboards, diagrams, flowcharts, and project plans from AI conversations. 17 MCP tools for board management, element creation, and real-time collaboration.1MIT
- AlicenseNot gradedqualityDmaintenanceEnables AI agents to create and manage collaborative whiteboards with sticky notes, shapes, charts, and more, directly in Overboard Studio.MIT
- AlicenseNot gradedqualityBmaintenanceEnables AI agents to create and manipulate live visual diagrams on an Excalidraw canvas in real-time via MCP tools.3,095 npm38 PyPI14BSD 3-Clause
- AlicenseNot gradedqualityDmaintenanceEnables 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 npm8MIT