create_design_reference
Adds a link to a design, so the Figma file or the API contract a person pastes into the conversation lands on the record.
Add a design reference to a project: project_id, title and url are required; kind is other by default or one of figma, wireframe, prototype, screenshot, api_contract, sequence_diagram, erd, document; referenceable_type is project by default or component with the component's id in referenceable_id; version and notes (HTML) fill in the rest. The reference is written through the same action the Designs page and the intake wizard run, and design_reference.created goes out. A staff token with design-reference:create on the project is needed.
Requires ability
The token behind the MCP session must hold it, or the call is refused with TOKEN_MISSING_ABILITY.
Runs the same action as
The REST endpoint and this tool share one action, so validation, permissions and events are identical.
Fires one event
Delivered to every endpoint subscribed to it once the change is made.
Annotations
A client that honours annotations asks a person before running it.
Arguments
project_id*stringUUID of the project.
title*stringWhat the reference is called, 2 to 160 characters.
url*stringWhere the design lives, as a full URL.
kindstringoptionalWhat the link points at; other by default.
figmawireframeprototypescreenshotapi_contractsequence_diagramerddocumentotherreferenceable_typestringoptionalWhat the reference hangs off: project by default, or component.
projectcomponentreferenceable_idstringoptionalUUID of the component when the target is a component.
versionstringoptionalThe version or revision of the design, as the designer labels it.
notesstringoptionalWhat to look at and why, as HTML.
What it returns
{ "data": { "id": "3b4c5d6e-7f8a-4b9c-8d0e-1f2a3b4c5d6e", "project_id": "7f3d1c92-8b45-4e6a-9d21-5c8e0a4b6f13", "referenceable_type": "component", "referenceable_id": "c0a1b2c3-d4e5-4f60-8a7b-9c0d1e2f3a4b", "kind": "figma", "title": "Order flow", "url": "https://www.figma.com/file/abc123/order-flow", "version": "v1", "notes": "<p>The three screens of placing an order; the payment step is a placeholder.</p>", "added_by": "5b6c7d8e-9f0a-4b1c-8d2e-3f4a5b6c7d8e", "position": 1, "created_at": "2026-10-28T09:40:00+00:00", "updated_at": "2026-10-28T09:40:00+00:00" }}How it fails
VALIDATION_FAILEDtitle or url missing, a url that is not an address, a kind or target outside its set, or a component target without a component of the project.
RESOURCE_NOT_FOUNDunknown project_id, or a project outside the token's scope or the person's visibility.
FORBIDDENthe token is a client guest's, or the holder's role on the project does not carry design-reference:create.
TOKEN_MISSING_ABILITYtoken lacks design-reference:create.
How is this guide?
Last updated on