Overview

The DEON MCP server is a hosted Model Context Protocol endpoint that lets LLMs and agents work with DEON projects in natural language — placing items on a canvas, connecting and styling them, uploading and fetching images, and retrieving project knowledge (RAG).

Every tool call is translated into the same requests the DEON web client makes, so anything an agent creates or edits shows up live in the project for all collaborators.

At a Glance

Transport	Streamable HTTP (stateless)
Endpoint	POST https://api.deon.cloud/mcp
Authentication	DEON API token (deon_tk_…) in the Authorization header
Capabilities	Tools only (no resources or prompts) — see Available Tools
Health check	GET https://api.deon.cloud/health

See Connecting for client configuration examples.

Compatibility

Tool changes are additive: new tools and new optional parameters, never a renamed or removed tool, a parameter that becomes required, or a parameter whose meaning changes. A client that cached the tool list before a deploy keeps working with it. get_data_model names the build that answers (server.version, server.environment), which is also the serverInfo.version of the initialize result.

Data Model

A DEON project is a map of items on an infinite 2D canvas:

• Coordinates are world units. position is the item's top-left corner as { x, y }.
• Size is the bounding box as { width, height }.
• Rotation is angle in degrees (0–360).
• Fixed value sets — item kinds, shape types, text alignments, connector line types and markers — are enums in each tool's input schema, so a client can validate a call before sending it. The server takes a value in another case as the schema spells it ("rectangle" → "Rectangle") and rejects anything else with an error that lists the allowed ones. It also rejects arguments a tool does not have, so a typo such as fillColour is reported rather than ignored.
• Colors are hex strings — "#RRGGBB" (e.g. "#3B82F6"), or "#AARRGGBB" for alpha (alpha first). Never objects, and never CSS forms such as rgb()/rgba(), hsl() or named colors: those are rejected by the API's validation.

The item types, their fields and the shape catalogue come from get_data_model at runtime, so an agent can look them up mid-conversation; they match the REST Project Item API.

Available Tools

Tool	Description
list_projects	List the projects the caller can access.
get_project	Read a project's canvas: a summary, or its items with chosen fields, filtered and paged.
update_project	Rename a project or change its canvas background color.
find_item	Resolve an item id to the project that contains it.
create_item	Create a text item — a label or a sticky note.
create_items	Create many items and their connectors in one call — the way to build a diagram.
create_shape	Place a geometric shape (rectangle, ellipse, arrow, star, …) on the canvas.
connect_items	Draw a connector (line/arrow) between two existing items.
style_item	Change an item's colors, stroke, or font size — mapped per item type.
update_item_property	Set a single property of an item by its friendly name.
delete_item	Remove an item from a project.
arrange_item	Move an item to the front or back of its container, or one step.
upload_image	Upload an image (base64 or URL) and place it on the canvas.
get_image_data	Download the bytes of an image item or stored file.
render_view	Render part of a board as an image to check what you built.
retrieve_knowledge	Semantic search (RAG) over a project's indexed knowledge.
knowledge_status	Report whether a project's knowledge is indexed and retrievable by the caller.
get_data_model	Return the DEON data-model reference (item types, fields, shape names).

Typical Workflow

1. list_projects — discover project ids.
2. get_project — read the canvas: summary: true first, then only the items you need; item ids from the result feed the editing tools. Already have an item id but no project id? find_item resolves it.
3. create_items — add a diagram or board section in one call; create_item / create_shape / upload_image for single items.
4. connect_items, style_item, update_item_property, arrange_item — connect, style, refine, and fix the stacking order; update_project renames the project or recolors the canvas.
5. retrieve_knowledge — ground answers in the project's actual content. Knowledge has to be analysed first, per user and tenant; if a retrieval comes back empty, knowledge_status says whether that means "not analysed" or "no match".

note

https://api.deon.cloud is a placeholder for your deployment's public hostname throughout these docs.