find_item

Resolve a canvas item id to the project that contains it — use this when you have an item id (e.g. one pasted by the user) but no project id, before calling update_item_property, style_item, delete_item, or connect_items. Returns the owning project plus the item with every get_project field (style, zIndex, autoSize, connector ends, ...). Pass projectId to check that one project; otherwise the caller's projects are searched, most recently updated first.

Without it the only way to resolve an id is to call get_project for every candidate project and scan the returned item list.

Tool name: find_item

Parameters

Parameter	Type	Required	Default	Description
itemId	string	Yes	—	The canvas item id to resolve.
projectId	string	No	—	Restrict the lookup to this project instead of searching all accessible projects.
maxProjects	number	No	50	Max projects to search when no projectId is given.
searchTemplates	boolean	No	false	Also search template projects.

Returns

The owning project plus the item with every get_project field except html:

{
  "projectId": "a1b2c3d4-...",
  "projectName": "Product Roadmap",
  "tenantId": 42,
  "projectsSearched": 3,
  "item": {
    "id": "a1e511f7-...",
    "kind": "label",
    "position": { "x": 100, "y": 200 },
    "size": { "width": 240, "height": 48 },
    "text": "Q3 Goals",
    "parentId": "f0e1d2c3-...",
    "zIndex": 3,
    "angle": 0,
    "autoSize": "none",
    "backgroundColor": "#00000000",
    "textColor": "#1F2937",
    "fontSize": 16
  }
}

projectsSearched is how many projects were loaded before the hit — 1 when projectId was given.

When the item is not found, the tool returns an error whose message starts with NOT_FOUND:.

Search Order and Scope

• Without projectId, the caller's projects are searched most recently updated first, up to maxProjects. The item a user just copied is almost always in a recently touched project, so the hit usually comes within the first few.
• Projects that cannot be loaded are skipped rather than failing the lookup.
• Templates are excluded unless searchTemplates is set; they are then merged into the same most-recently-updated ordering.
• Like every tool, the search only covers the environment this MCP server targets. An id from a different environment reports NOT_FOUND.

tip

Pass projectId whenever it is already known. It turns the scan into a single project load and confirms the id without transferring the full item list of a large map.

Example

"Write 'Shipped' into label a1e511f7-…"

{ "itemId": "a1e511f7-..." }

Then feed the returned projectId into update_item_property.