link_artefacts
Join two artefacts of a project with a kind read from the source, such as a story that implements a requirement; a repeat, a self-link or a foreign end is refused, and link.created goes out.
Join two artefacts of one project: source_type and source_id, target_type and target_id (each type one of epic, work-item, requirement, business-rule, use-case, raid-item, decision, data-entity or glossary-term), a kind read from the source (implements, derives_from, verifies, covers, depends_on, blocks, relates_to, duplicates, caused_by, fixed_by or supersedes; relates_to when left out) and an optional note of up to 300 characters. The link is returned with both ends named, and link.created goes out.
Link a story to the requirement it implements and the rule it honours when you pick it up, a bug to the story that fixes it, a decision to the epic it shapes, so the record is true without anyone redrawing it. Both ends must be artefacts of the same project and not the same artefact, and the same kind joins two artefacts once (relates_to and duplicates read the same from both sides, so the reverse direction counts as the same link): a repeat is refused rather than doubled, which makes the tool safe to call again. Removing a link stays with people. The links are internal: a guest token is refused.
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
Sending the same arguments twice changes nothing the second time.
Arguments
project_id*stringUUID of the project both artefacts belong to.
source_type*stringThe source artefact's type.
epicwork-itemrequirementbusiness-ruleuse-caseraid-itemdecisiondata-entityglossary-termbaselinechange-requestsource_id*stringUUID of the source artefact.
target_type*stringThe target artefact's type.
epicwork-itemrequirementbusiness-ruleuse-caseraid-itemdecisiondata-entityglossary-termbaselinechange-requesttarget_id*stringUUID of the target artefact.
kindstringoptionalHow the source relates to the target; relates_to by default.
implementsderives_fromverifiescoversdepends_onblocksrelates_toduplicatescaused_byfixed_bysupersedesnotestringoptionalA few words on why, up to 300 characters.
What it returns
{ "data": { "id": "d4e5f6a7-b8c9-4d0e-9f1a-2b3c4d5e6f70", "project_id": "7f3d1c92-8b45-4e6a-9d21-5c8e0a4b6f13", "source_type": "work-item", "source_id": "0f9e8d7c-6b5a-4c3d-8e2f-1a0b9c8d7e6f", "source_reference": "CRM-142", "source_title": "Apply a voucher at checkout", "target_type": "requirement", "target_id": "3a4b5c6d-7e8f-4a9b-8c0d-1e2f3a4b5c6d", "target_reference": "CRM-FR-12", "target_title": "The checkout accepts a voucher", "kind": "implements", "phrase": "implements", "inverse_phrase": "is implemented by", "note": "The voucher flow is where the rule bites", "created_by": "c3d4e5f6-a7b8-4c9d-8e0f-1a2b3c4d5e6f", "created_at": "2026-10-28T09:20:00+00:00" }}How it fails
VALIDATION_FAILEDa missing or unknown type, id or kind; the two ends are the same artefact; an end belongs to another project; the same link already exists; a note over 300 characters.
RESOURCE_NOT_FOUNDunknown project_id, or an end the token may not see.
FORBIDDENa guest token: the links are internal.
TOKEN_MISSING_ABILITYtoken lacks link:create.
How is this guide?
Last updated on