# MCP connector reference

Category: AI and integrations
Last updated: 2026-09-21
Canonical: https://traceabledocs.com/docs/mcp-reference

**Audience:** Traceable users (document authors, project contributors, reviewers,
and the org admins who grant access). No coding knowledge is assumed.
**Applies to:** the Traceable MCP server `traceable` v4.0.0, 21 tools.
**Last updated:** 2026-09-21

---

## 1. What this is

The Traceable App MCP connector lets an AI assistant (Claude on claude.ai, Claude
Desktop, or Claude Code) work inside your Traceable account the same way you do:
it can browse your projects, read documents, write and edit content, build ID
grids, create trace links, and pull material out of your Reference Library.

Two things are worth understanding before you connect:

1. **The assistant acts as you.** It signs in with your account through a consent
   screen, and it can reach exactly what you can reach, no more. If you are not a
   member of a project, neither is the assistant. If your role is read-only, the
   assistant is read-only too.
2. **It only touches drafts, and every change is attributable.** Publishing,
   review, and e-signature stay human actions in the app. Every edit the
   assistant makes is written to the audit log against your name, and (unless an
   admin turns the setting off) each edited row waits for you in the document's
   **Agent** panel for you to read and accept.

Think of it as a very fast co-author who can draft, restructure, and cross-link,
while you keep the pen for anything that makes a document official.

---

## 2. Before you start

You need three things:

| Requirement | How to get it |
|---|---|
| A Traceable account | Sign in at `https://app.traceabledocs.com` |
| **Your organisation allows external agents** | On by default. An org admin can turn it off for everyone (see below). |
| **MCP access enabled on your user** | **Off by default.** An org admin turns on **Enable MCP access** for you. |
| An MCP client | claude.ai, Claude Code, or another client that takes a server URL (section 3) |

### Two switches, and both must be on

Access is governed at two levels, and a refusal at either one stops the
connection:

1. **The organisation** must permit external agents at all. This is on by
   default, so nothing changed for organisations that already had the connector
   working.
2. **You** must be granted access individually. This is off by default.

**If you belong to more than one organisation, every one of them must permit
external agents.** The connection is granted to *you*, not to one organisation,
so a connected assistant reaches everything you can reach across all of them. An
organisation that switches external agents off is saying that no outside agent
touches its data, and that is only true if the switch also covers members who
happen to belong to a second, more permissive organisation. The cost is real:
one organisation can cut you off from the others.

### Turning it on (org admins)

**Per person.** Go to **Organisation → Members**, open the member, and in the
**AI / integrations access** box switch **Enable MCP access** on.

**For the whole organisation.** Go to **Organisation settings → External
agents**.

Either switch is an immediate cut-off when turned off: the member's connector
stops working straight away, even mid-session, without waiting for anything to
expire.

Both control **whether** a person may connect. Neither changes **what** they can
see: project and organisation membership decides that, exactly as in the web
app.

---

## 3. Connecting

The server address is:

```
https://app.traceabledocs.com/api/mcp/mcp
```

### On claude.ai (web, desktop, mobile)

1. Open **Settings → Connectors**.
2. Choose **Add custom connector**.
3. Paste the address above and save.
4. Claude sends you to Traceable's sign-in and then to a consent screen headed
   *"Authorize … wants to connect to your Traceable account"*.
5. Check the permissions listed, then approve.

### In Claude Code

```bash
claude mcp add --transport http traceable https://app.traceabledocs.com/api/mcp/mcp
```

Then start Claude Code and follow the browser sign-in and consent prompt the
first time a Traceable tool is used.

### In other clients

The connector is an ordinary remote MCP server: streamable HTTP, with OAuth
sign-in handled by the client. Any client that accepts a custom server URL can
use it, and the sign-in and consent steps are the same ones described above.

> **Not yet verified by us.** The clients below are expected to work because
> they speak the same protocol, but we have not run each one end to end. If you
> connect one successfully, or hit a problem, tell us through the in-app
> **Support** menu (section 12) so this list can say so with confidence.

| Client | Where to put the URL |
|---|---|
| ChatGPT | Developer mode, as a custom connector |
| Cursor | MCP settings, as an HTTP server |
| VS Code | MCP settings, as an HTTP server |
| Gemini | Configure it yourself as a custom MCP server. Traceable is not in Google's connector directory, and Google runs no submission process for it. |

**Clients that only speak stdio or SSE.** Some older clients cannot talk to an
HTTP server directly. Put `mcp-remote` in front:

```bash
npx mcp-remote https://app.traceabledocs.com/api/mcp/mcp
```

There is no SSE endpoint to connect to instead. SSE is switched off
deliberately: supporting it would mean running a Redis instance purely to hold
connection state, and the HTTP transport needs no such thing.

### What you are agreeing to on the consent screen

| Permission shown | What it allows |
|---|---|
| Read your projects and documents | Browsing projects, document maps, link maps, templates, document content, and the Reference Library |
| Create and edit document content | Creating and editing draft documents, rows, ID grids, trace links, and references |

Approving grants both by default. Access is time-limited behind the scenes: the
short-lived key the assistant holds lasts up to an hour and is renewed silently
for up to 30 days of continued use, after which you sign in again.

#### Who is asking

Below the permissions, an **About this application** box shows what Traceable
actually knows about the client:

| Field | What it means |
|---|---|
| Website | The address the application gave for itself, shown as plain text |
| Sends you back to | The address you will be returned to after approving |

**"Sends you back to" is the one field worth reading closely.** It is the only
line on the screen that Traceable verified rather than took the application's
word for: it has to match, exactly, what the application registered in advance,
so it is the one thing a bad actor cannot change after the fact. If it is not a
host you expect, do not approve.

You will also see the line *"This application registered itself. Traceable has
not verified it."* That is literally true, and it is why **no logo is shown**.
Any application may register itself and call itself anything, including
"Traceable Official". Rendering its logo would make a claim it made about itself
look like one we checked, on the exact screen where you are deciding whether to
trust it. So you get hostnames as text, and links to the application's own
privacy policy and terms if it supplied them, and nothing dressed up as an
endorsement.

### If you are told you do not have access

Signing in with an account that has not been granted MCP access does not leave
you stuck. You get a page that names your organisation and explains which of the
two switches in section 2 is closed:

- **Your account is not permitted yet.** This is the common case, and the page
  offers an **Ask an administrator for access** button that emails your
  organisation's admins. They decide. You can connect once one of them grants it.
- **Your organisation has turned external agents off.** An admin has to change
  that under **Organisation settings → External agents**. There is no button
  here, because no email to an admin would let *them* clear it for you alone.

In every case nothing has been shared with the application at the point you are
refused.

---

## 4. What the assistant can see

Access mirrors your own, through the same checks as the web app:

- **Projects:** only projects you are a member of, and only active ones.
- **Organisations:** only organisations you belong to.
- **Documents:** every document in those projects, subject to your project role.
- **Role limits:** an **auditor** sees published documents only, so an assistant
  acting for an auditor cannot read a draft. **Reviewers** can read drafts but
  cannot write. **Contributors** and **admins** can read and write.
- **Reference Library:** organisation-scoped items, plus items in projects you
  belong to.

Same rule for writing: if your role cannot edit a document in the app, the
assistant cannot edit it either, and the tool returns an access error.

---

## 5. What the assistant can do

You do not type tool names. You ask in plain language and the assistant picks the
tools. The groups below tell you what is in reach, so you know what to ask for.

### Workspace

- List your organisations and projects, with your role in each.
- Produce a **document map** of a project: groups, documents, document numbers,
  ID prefixes, types, statuses, versions, item counts, and heading outlines.
- Produce a **link map**: which documents trace to which, with link counts,
  including one-to-many relationships and links out to external documents.
- List the templates available to you (system templates plus your organisation's).
- Read a document as an outline (cheap) or in full, or just a slice of it.

*"Map the TD01 project and tell me which documents have no incoming trace links."*

### Documents and content

- Create a document in a project, optionally from a template, with a name,
  document number, TraceID prefix, type, and group.
- Replace a whole segment (header, body, footer, or the title page equivalents).
- Insert one or more blocks at a chosen point: after a given TraceID, after a
  given row, or at the start or end of the body.
- Replace a single block, identified by its TraceID or its row position.
- Delete a block. Deletes are soft, so a mistake is recoverable in the app, and
  deleting a table or grid header removes its children with it.
- Update document metadata: name, number, type, group, and heading auto-numbering.

Content the assistant can author includes headings and paragraphs, traceable
rows, tables, multi-column bands, ID grids, table of contents, revision tables,
signature tables and signature rows, publish logs, document lists, traceability
matrices, diagrams, page and section breaks (including paper size and
orientation), and property tokens such as `{{docTitle}}`.

*"Draft a 12-requirement Functional Requirements document from the user needs in
TD01-002, using our FRS template, prefix FR."*

### Traceability

An ID grid is the mechanism traceability is made of: its rows carry the TraceIDs
and its link columns carry the links. So the grid tools and the link tools belong
together, and the assistant reaches for them as one set.

Grids matter because they are the part of a document most easily damaged by a
wholesale rewrite. These edit in place and keep every row's identity and trace
links intact:

- Add a column (id, text, link, calculation, dropdown, test result, or checkbox).
- Rename a column header.
- Change a column's type, including dropdown options and calculation sources.
- Set a single cell's value.

Summary columns are the one exception: they are built in the app only. Link cells
are also not set directly, you ask for a trace link instead and the chip is
placed for you.

*"Add a 'Verification method' dropdown column to the grid in DRS with options
Test, Inspection, Analysis, Demonstration."*

And the links themselves:

- Create a trace link between two TraceIDs in a project. It is idempotent, so
  asking twice does not create a duplicate. When the source is an ID row, the
  link chip is also placed in a link column so it is visible on the page. If the
  row has no link column, the link is still created and the assistant tells you
  why nothing is showing.
- Delete a trace link, named by the two TraceIDs it runs between. The direction
  matters: asking to delete FR-1 to UN-2 will not delete a link that runs UN-2 to
  FR-1, it tells you the link runs the other way.
- **Rename a TraceID in place** without breaking anything: links into and out of
  the row survive, the grid's id cell stays in sync, and cached labels elsewhere
  in the project are refreshed.
- **Rename a document's whole TraceID prefix**, re-deriving every row's visible
  id while preserving links. You do not need to rebuild a document to re-prefix it.

*"Renumber the ID grid in TD01-004 so the ids run DR-1 to DR-40 with no gaps."*

### Library

- List the items you can access, with REF code, kind, file type, scope, and
  whether the text has been indexed.
- Keyword search across indexed item text, returning a snippet per hit.
- Read an item's extracted plain text.
- Index an item so its text becomes searchable and cheap to read.
- Attach a library item, or another document, as a reference on a document,
  creating the Reference Table row if one is not there yet.

Search is plain keyword matching over text extracted on Traceable's own servers.
There is no embedding service and no third-party call, so nothing leaves the
system to make search work.

*"Search the library for 'IEC 62304 software safety classification' and cite the
best match on TD01-003."*

---

## 6. What the assistant cannot do

Deliberate limits, not gaps to work around:

| Not available | Why, and what to do instead |
|---|---|
| Publishing a document | Publishing creates the controlled version. It stays a human action in the app. |
| Reviews, approvals, e-signature | Same reason. Sign in the app. |
| Editing a published document silently | A write to a published document opens a **new draft** first (see section 7). The published version is untouched in history. |
| Creating projects, organisations, or users | Account and project administration is app-only. |
| Deleting a live document | Only an **archived** document can be deleted, and that deletion is permanent. Archive it in the app first. |
| Uploading images or attachments | Images already in a document read back fine, but the assistant cannot add new ones yet. |
| Cross-references between rows | Readable, not yet writable. |
| Hand-authoring a Reference Table | Ask for a reference to be added and the table row is provisioned automatically. |
| Reading PDFs, PowerPoint, or images in the library | Text extraction covers Word, spreadsheets, CSV, text and markup formats, and web pages. Other types report back as unsupported rather than guessing. |
| Merged cells in a band converted to a table | Reading is lossy and a wholesale rewrite flattens the merges. Edit those bands in the app. |

---

## 7. What happens to your documents when the assistant edits them

**Drafts, always.** If a document is published, the first write reopens it as a
new draft (for example v1.0 becomes v1.1) and the published version stays intact
in history. If it is already a draft, a burst of edits opens one new draft
increment, so an assistant's editing pass gets its own line on the **Versions**
timeline, just like one of your own editing sessions.

**Rows wait for your acceptance.** Each project has a **Require AI change review**
setting (Organisation → Projects, admin only), on by default. While it is on,
every row an assistant writes is flagged and appears in the document's **Agent**
panel under **Pending**, with the row preview and its TraceID. Contributors and
admins get an **Accept** button, and accepted changes move to the **Accepted**
list. The panel is empty when there is nothing waiting.

**Deletes are recoverable.** Block deletions are soft, matching what deleting a
row in the editor does. Links pointing at a deleted row are marked broken rather
than vanishing, so nothing disappears quietly.

**Everything is logged.** Each change writes an append-only audit log entry
attributed to you as the acting user, so agent-assisted authoring keeps the same
provenance trail as manual authoring.

---

## 8. Getting good results

**Name things precisely.** Document numbers (TD01-003), TraceIDs (FR-012), and
REF codes (REF-00001A) remove all guesswork. If two projects share a name across
different organisations, name the organisation too.

**Ask for a map before a rewrite.** "Map the project, then propose what to change"
costs little and prevents the assistant from working with a stale picture.

**Prefer targeted edits to wholesale rewrites.** Replacing a whole segment
soft-deletes the rows in it and marks links to them broken. Asking to "update
FR-012" or "add a column to that grid" preserves row identity and links. If you
want a rewrite, say so explicitly, and expect to re-link.

**Work in batches you can review.** A dozen rows you read and accept beats two
hundred you skim.

**Some prompts that work well:**

- "Read TD01-002 and list every user need that has no downstream requirement."
- "Create a Design Requirements document from the FRS, one DR per FR, prefix DR,
  and trace each DR back to its FR."
- "In TD01-004, set the Verification column to 'Test' for every row whose text
  mentions measurement."
- "Check the link map for orphaned documents and summarise the gaps."
- "Add REF-00012B as a reference on TD01-003 and cite it in the introduction."

**A note on row numbers.** Inserting a row renumbers the rows after it. The
assistant handles this by re-reading or by anchoring to TraceIDs, but if you see
it editing what looks like the wrong row, ask it to re-read the document first.

---

## 9. Managing and revoking access

### Your own connections

Go to **Account → Connected apps**. Each app you have authorised is listed and can
be revoked. Revoking stops that app obtaining new access; access it already holds
stops working within the hour.

### As an org admin

- **Organisation → Members → (member) → Active connections:** revoke a specific
  connection for that member.
- **Enable MCP access** off: the immediate, total cut-off for that user, across
  every client they have connected.

### What is recorded

Connector access leaves its own trail, separate from the document audit log.
Authorising an application, declining one, being refused access, requesting
access and revoking a connection are each recorded with a timestamp. So the
question an auditor asks, which is who allowed an outside system to reach
controlled content and when, is answerable from the record rather than from
memory.

Document edits an assistant makes are recorded where all edits are: in the
document's audit trail, against your name.

### Good practice

- Revoke connections you no longer use.
- Review a departing member's connections as part of offboarding.
- Leave **Require AI change review** on for regulated projects.

---

## 10. Troubleshooting

| Symptom | Cause and fix |
|---|---|
| Sign-in loop, or the connector reports it is unauthorised | MCP access is not enabled for your user. Ask an org admin to turn on **Enable MCP access**. |
| The connector was working and suddenly stopped | The connector is served by the running app, so it drops on every production deployment. Reconnect, or ask the assistant to retry, and it re-authorises. |
| "This action requires the documents:write scope" | The connection was authorised for reading only. Remove it in **Account → Connected apps** and reconnect, approving both permissions. |
| "Document not found or access denied" | You are not a member of that project, or your role cannot edit. Check your role, or ask to be added. |
| "This document has no published version available to your role" | You are an auditor on that project and the document has no published version. Auditors read published documents only. |
| A grid change is refused, or the document will not accept edits | The target may be a template, or the write may be blocked by role. Templates can be read and cloned, not edited through the connector. |
| Edits do not appear on the page | Check the **Agent** panel: the rows are probably pending your acceptance. |
| A trace link was created but no chip is visible | The source row has no link column. Add one, then ask for the link again. |
| A library search finds nothing | The item may not be indexed, or its type may be unsupported (PDF, PowerPoint, images). Ask for it to be indexed first. |
| Content the assistant wrote to the title page does not show | The document's title page is switched off. Turn it on in the app and the content renders. |

---

## 11. Every tool, in full

You never call these by name. The assistant chooses them, and this section exists so you can
check what it is able to do and on what terms. Every tool below is listed with the permission it
needs and every parameter it accepts, taken from the implementation rather than from a summary,
so it does not drift from what the server actually exposes.

A parameter marked required must be supplied for the call to run at all. One marked optional has
a default the description names. Where a parameter takes a fixed set of values they are listed;
anything else is rejected before the tool runs.

There are **21 tools**: **7** need read access and **14** need write access.

Each tool below also says whether it changes anything, whether asking for it twice does the job
twice, and whether it reaches outside Traceable. Your assistant is told the same three things, and
uses them to decide what to confirm with you. Claude, for example, lets you approve all the
read-access tools in one go, because they change nothing, and asks every single time for the
others.


### Workspace

Find your way around: what exists, and where.


#### `traceable_workspace_projects`

_**Read access.** Changes nothing, safe to ask for twice._

Your workspace: every organisation you belong to (id, name, org number, your role), each with the
active projects in it you are a member of (id, name, project number, your role, document count,
last-updated time). Start here, a projectId from this listing is the input to
traceable_workspace_map. Organisations you belong to but have no project in are listed with an
empty projects array: their organisationId is what traceable_library_search and
traceable_workspace_templates take. Projects with no organisation come back under
projectsWithoutOrganisation. Pass organisationId to narrow to one organisation, which is how you
disambiguate same-named projects across organisations.

| Parameter | Type | Required | Meaning |
|---|---|---|---|
| `organisationId` | UUID | no | Only list this organisation and its projects |


#### `traceable_workspace_templates`

_**Read access.** Changes nothing, safe to ask for twice._

List the document templates available to you (system templates plus your organisations'): id,
name, TraceID prefix, document type, band previews, body outline, and the owning organisation
(organisationId + organisationName; null for a system template). Pass a template's id as
templateId to traceable_doc_create to clone its styled header/footer bands and body scaffold.

_Takes no parameters._


#### `traceable_workspace_map`

_**Read access.** Changes nothing, safe to ask for twice._

Survey a project before opening any document. include=structure (default) returns the
group/document/outline tree: each document's number, ID prefix, type, status, version, item counts
and H1-H6 headings, use it to decide what to read. include=links returns the document-to-document
trace graph instead: which documents link to which, how many trace links each edge carries and how
many distinct source rows they leave from, including one-to-many relationships and links to
external documents. include=both returns the two together. Returns Markdown by default (token-
efficient, readable); pass format=json for the structured object.

| Parameter | Type | Required | Meaning |
|---|---|---|---|
| `projectId` | UUID | **yes** | The project UUID (from traceable_workspace_projects) |
| `include` | `structure` \| `links` \| `both` | no | structure (default): the document tree. links: the trace graph between documents. both. |
| `format` | `markdown` \| `json` | no | markdown (default) or json |


### Documents

The document as a whole: read it, make one, change its metadata, remove it.


#### `traceable_doc_read`

_**Read access.** Changes nothing, safe to ask for twice._

Read a document or a template. mode=outline returns metadata + heading outline + item counts
(cheap; default when exploring). mode=full returns the content as Traceable Markdown (TrMD):
segments as [[segment …]], each block prefixed with its [[row N]] anchor annotation, including ID-
grid structure ([[id-header types=…]]). Bound a full read with fromOrder/toOrder (row orders from
the outline or a prior read) to load only a section. Accepts a template id (from
traceable_workspace_templates) so you can inspect a template body and its column structure before
cloning it with traceable_doc_create.

| Parameter | Type | Required | Meaning |
|---|---|---|---|
| `documentId` | UUID | **yes** | A document or template UUID (from traceable_workspace_map / traceable_workspace_templates) |
| `mode` | `outline` \| `full` | no | outline (default) or full |
| `fromOrder` | `number` | no | First row order to include (full mode) |
| `toOrder` | `number` | no | Last row order to include (full mode) |


#### `traceable_doc_create`

_**Write access.** Only adds things, asking twice does it twice._

Create a document in a project. templateId clones an org/system template (header/footer bands,
revision + signature scaffolding come along, discover templates with
traceable_workspace_templates); trmContent then authors the body. Without a template, default
header/footer bands are seeded for any segment trmContent does not provide. Returns the new
documentId and the created rows with their row orders.

| Parameter | Type | Required | Meaning |
|---|---|---|---|
| `projectId` | UUID | **yes** | The project UUID (from traceable_workspace_projects) |
| `name` | `string` | **yes** | Document name |
| `documentNumber` | `string` | no | Document number (e.g. TD01-003) |
| `idPrefix` | `string` | no | TraceID prefix (uppercase letters/digits/hyphens, e.g. FR) |
| `documentType` | `string` | no | Document type from the organisation taxonomy |
| `groupId` | UUID | no | Document group UUID (from traceable_workspace_map) |
| `templateId` | UUID | no | Template document UUID to clone |
| `trmContent` | `string` | no | Initial TrMD content (body only when templateId is set) |


#### `traceable_doc_update_meta`

_**Write access.** Overwrites or removes things, safe to ask for twice._

Update a document's metadata: name, document number, document type, group, and the
numberedHeadings toggle. Turn numberedHeadings on so the app auto-numbers headings, then author
heading text WITHOUT section numbers (see the headingNumbering note in traceable_capabilities).
Only the fields you pass are changed. To change the TraceID prefix use traceable_doc_rename_prefix
(it re-derives existing ids); it is not settable here.

| Parameter | Type | Required | Meaning |
|---|---|---|---|
| `documentId` | UUID | **yes** | The document UUID |
| `name` | `string` | no | New document name |
| `documentNumber` | `string` \| `null` | no | New document number, or null to clear |
| `documentType` | `string` \| `null` | no | New document type, or null to clear |
| `groupId` | UUID \| `null` | no | Move to this group UUID, or null to ungroup |
| `numberedHeadings` | `boolean` | no | Turn heading auto-numbering on or off |


#### `traceable_doc_rename_prefix`

_**Write access.** Overwrites or removes things, safe to ask for twice._

Rename a document's TraceID prefix in place, re-deriving every existing row's visible id
(traceable rows, native-table trace cells, and ID-grid id cells). Trace links are preserved, only
the human-readable ids change, so you do NOT need to recreate the document to re-prefix it. The
document must be an editable draft (published documents are read-only).

| Parameter | Type | Required | Meaning |
|---|---|---|---|
| `documentId` | UUID | **yes** | The document UUID |
| `newPrefix` | `string` | **yes** | New prefix: 1–12 uppercase letters, digits, or hyphens (e.g. IQ-R) |


#### `traceable_doc_delete`

_**Write access.** Overwrites or removes things, safe to ask for twice._

Permanently delete a document and all its content (items, columns, trace links, versions).
IRREVERSIBLE. To guard against accidents this mirrors the app: only a document that has been
ARCHIVED may be deleted, archive it in the app first, otherwise this returns an error. Use it to
remove a superseded document after replacing it.

| Parameter | Type | Required | Meaning |
|---|---|---|---|
| `documentId` | UUID | **yes** | The archived document UUID to delete |


### Content

Authoring inside a document: segments and blocks.


#### `traceable_segment_write`

_**Write access.** Overwrites or removes things, safe to ask for twice._

Replace a whole segment with the given TrMD, the primary bulk-authoring tool. Existing rows in the
segment are soft-deleted (links to them are marked broken), so use
traceable_block_write/traceable_block_update for incremental edits. Author multi-column bands with
[[column-start count=N]] … [[column-break]] … [[column-end]] (one rich-text cell per column), and
ID grids with [[id-header types=id,text,link]] + a label row followed by [[id-row id=…]] rows
(link cells take whitespace-separated TraceID names). The title_* segments are the optional title
page; writing to them on a document whose title page is switched off stores the content but it
will not render until the page is enabled in the app.

| Parameter | Type | Required | Meaning |
|---|---|---|---|
| `documentId` | UUID | **yes** | The document UUID |
| `segment` | `header` \| `body` \| `footer` \| `title_header` \| `title_body` \| `title_footer` | **yes** | Which segment to replace |
| `trmContent` | `string` | **yes** | Traceable Markdown (TrMD). GitHub-flavored Markdown plus [[directive]] blocks, see traceable_capabilities. Read-only annotations ([[row]]/[[document]]) are rejected. |


#### `traceable_block_write`

_**Write access.** Overwrites or removes things, asking twice does it twice._

Insert one or more body blocks at an anchor: after a TraceID (afterItemId), after a [[row N]]
anchor (afterOrder, from a document read), or at the start/end of the body (position; default
end). Returns the created rows with their new row orders, plus a `renumbered` marker when the
insert shifted existing rows. IMPORTANT: an insert renumbers every row after the anchor, so row
orders from earlier reads/responses go stale, re-read before further order-based calls, or anchor
by TraceID (immune to renumbering).

| Parameter | Type | Required | Meaning |
|---|---|---|---|
| `documentId` | UUID | **yes** | The document UUID |
| `trmContent` | `string` | **yes** | Traceable Markdown (TrMD). GitHub-flavored Markdown plus [[directive]] blocks, see traceable_capabilities. Read-only annotations ([[row]]/[[document]]) are rejected. |
| `afterItemId` | `string` | no | Insert after the row with this TraceID (e.g. FR-003) |
| `afterOrder` | `number` | no | Insert after this row order (the [[row N]] anchor) |
| `position` | `start` \| `end` | no | Fallback position in the body when no anchor is given (default end) |


#### `traceable_block_update`

_**Write access.** Overwrites or removes things, safe to ask for twice._

Replace one block. Identify it by its TraceID (itemId, e.g. FR-003) or by its [[row N]] anchor
(atOrder, must come from a read issued after the last insert; inserts renumber later rows).
trmContent must parse to exactly one block; page/section breaks in it replace the row's break
flags. TraceID renames are not supported, use traceable_trace_id_rename.

| Parameter | Type | Required | Meaning |
|---|---|---|---|
| `documentId` | UUID | **yes** | The document UUID |
| `trmContent` | `string` | **yes** | Traceable Markdown (TrMD). GitHub-flavored Markdown plus [[directive]] blocks, see traceable_capabilities. Read-only annotations ([[row]]/[[document]]) are rejected. |
| `itemId` | `string` | no | TraceID of the block to replace |
| `atOrder` | `number` | no | Row order of the block to replace (the [[row N]] anchor) |


#### `traceable_block_delete`

_**Write access.** Overwrites or removes things, safe to ask for twice._

Soft-delete one block (recoverable in the app). Deleting a table or ID header cascades to its
children, and links to deleted trace targets are marked broken, the same semantics as deleting the
row in the editor. atOrder must come from a read issued after the last insert (inserts renumber
later rows); the response echoes the deleted row's itemId, verify it hit the intended row. Prefer
itemId anchoring.

| Parameter | Type | Required | Meaning |
|---|---|---|---|
| `documentId` | UUID | **yes** | The document UUID |
| `itemId` | `string` | no | TraceID of the block to delete |
| `atOrder` | `number` | no | Row order of the block to delete (the [[row N]] anchor) |


### Traceability

ID grids and the links between rows. An ID grid is the mechanism traceability is made of, so the grid tools and the link tool live together.


#### `traceable_grid_column`

_**Write access.** Overwrites or removes things, asking twice does it twice._

Add a column to an ID grid, rename one, or change one's type, pick with op. NON-DESTRUCTIVE in
every case: existing cells and trace links are preserved (unlike traceable_segment_write, which
replaces the whole grid and breaks links). Identify the grid by its HEADER row (header.itemId or
header.atOrder). op=add gives every id-row a fresh cell: pass type, optionally insertAt (0-based
position; omit to append) and label (omit for the type default ID / Link / Column). op=set_label
renames a column's header text in place, leaving its type and cells alone: pass colIdx and label.
Use it to correct a mislabeled header (e.g. a default "Column"). op=set_type converts each id-row
cell to a new type: pass colIdx, type, and for typed columns config, { "options":
["Open","Closed"] } for a dropdown, { "op": "product", "sources": [1,2] } for a calculation. Only
one id column is allowed per grid. To set a CELL's value use traceable_grid_cell.

| Parameter | Type | Required | Meaning |
|---|---|---|---|
| `documentId` | UUID | **yes** | The document UUID |
| `header` | `object` | **yes** | Identify the row by itemId or atOrder (pass one). |
| `op` | `add` \| `set_label` \| `set_type` | **yes** | add a column, set_label to rename one, or set_type to convert one |
| `colIdx` | `number` | no | 0-based index of the column to act on (required for set_label and set_type) |
| `type` | `id` \| `text` \| `link` \| `calculation` \| `dropdown` \| `test-result` \| `checkbox` | no | Column type (required for add and set_type) |
| `label` | `string` | no | Header label (required for set_label; optional for add) |
| `insertAt` | `number` | no | 0-based column position to insert at (add only; default: append) |
| `config` | `object` | no | Per-column config (set_type only): dropdown {options:[…]} or calculation {op, sources:[colIdx…]} |


#### `traceable_grid_cell`

_**Write access.** Overwrites or removes things, safe to ask for twice._

Set one ID-grid cell's value, identified by the id-ROW (row.itemId or row.atOrder) and the 0-based
colIdx. NON-DESTRUCTIVE: the cell keeps its identity and the row's trace links survive, setting
the id column changes the visible TraceID without breaking links (unlike traceable_segment_write).
id/text columns take the raw value; test-result normalises PASS/FAIL; checkbox normalises to
true/false (true/yes/1/✓ vs false/no/0/✗); dropdown takes the chosen option. Link cells are NOT
settable here, use traceable_link instead.

| Parameter | Type | Required | Meaning |
|---|---|---|---|
| `documentId` | UUID | **yes** | The document UUID |
| `row` | `object` | **yes** | Identify the row by itemId or atOrder (pass one). |
| `colIdx` | `number` | **yes** | 0-based index of the column whose cell to set |
| `value` | `string` | **yes** | The new cell value |


#### `traceable_trace_id_rename`

_**Write access.** Overwrites or removes things, safe to ask for twice._

Rename a row's visible TraceID in place (a traceable row or an ID-grid row). The row keeps its
database identity, so every trace link into or out of it survives; an ID-grid row's id cell is
kept in sync and cached link labels that reference the old id are refreshed project-wide. Use this
instead of delete-and-reinsert, which would break links. To renumber a whole grid, call this once
per row (re-read afterwards is not needed, anchor by TraceID).

| Parameter | Type | Required | Meaning |
|---|---|---|---|
| `documentId` | UUID | **yes** | The document UUID containing the row |
| `fromItemId` | `string` | **yes** | The current visible TraceID (e.g. UN-1.1) |
| `toItemId` | `string` | **yes** | The new visible TraceID (e.g. UN-1), unique within the document |


#### `traceable_link`

_**Write access.** Overwrites or removes things, safe to ask for twice._

Create or delete a trace link between two TraceIDs (traceable rows, ID rows, or table trace rows),
resolved server-side within one project. Both ops address the edge THE SAME WAY, by the pair of
TraceIDs, which is the address a document read gives you: link columns render as TraceID names.
op=create is idempotent on the PAIR, not the direction (F914): if an edge already exists between
the two rows in EITHER direction, the existing edge is returned and nothing is written,
`existingDirection` says "same" or "opposite", and on "opposite" a `warning` explains that no chip
was placed because a second edge would be a cycle. When the source row is an ID Row, create also
writes the link into its link column so the chip SHOWS on the page, `placedInColumn` says which
column took it. The column chosen is the row's first OUTPUT link column, since the target is
downstream of the source; pass `toColumnIndex` to place it elsewhere. If the row has no link
column the edge is still created and pinned, and a `warning` explains why nothing is shown.
op=delete removes the edge AND the chip from the source row's link cell. Direction is not guessed:
if the pair exists only the other way round, nothing is deleted and the error says so, because in
a traceability chain the direction carries meaning.

| Parameter | Type | Required | Meaning |
|---|---|---|---|
| `op` | `create` \| `delete` | **yes** | create the edge, or delete it |
| `fromDocumentId` | UUID | **yes** | Document UUID containing the source TraceID |
| `fromItemId` | `string` | **yes** | Source TraceID (e.g. UN-4) |
| `toDocumentId` | UUID | **yes** | Document UUID containing the target TraceID |
| `toItemId` | `string` | **yes** | Target TraceID (e.g. FR-012) |
| `toColumnIndex` | `number` | no | create only: which of the source row’s link columns shows the chip; defaults to its first OUTPUT link column |


### Library

The Reference Library, and citing from it.


#### `traceable_library_search`

_**Read access.** Changes nothing, safe to ask for twice._

Find Reference Library items you can access (org-scoped items plus items in projects you are a
member of). With query: keyword search across each item's name, REF code, and locally-extracted
text (case-insensitive substring, no semantic/embedding search), returning matches with a short
snippet around the first hit. WITHOUT query: lists every accessible item, REF code, name, kind
(file | webpage), file type, scope (org | project), and whether its text has been indexed. Search
only finds text that has been indexed, so if a search comes back empty, list first and check the
indexed flag: an unindexed item is invisible to search until traceable_library_index runs on it.

| Parameter | Type | Required | Meaning |
|---|---|---|---|
| `query` | `string` | no | Keyword or phrase to search for. Omit to list every accessible item. |
| `organisationId` | UUID | no | Restrict to this organisation (defaults to your active org) |


#### `traceable_library_read`

_**Read access.** Changes nothing, safe to ask for twice. Fetches from the web, so it reaches outside Traceable._

Return the extracted plain text of a Reference Library item, identified by its REF code (e.g.
REF-00001A) or its id. Returns the stored indexed text when available, otherwise extracts on the
fly without persisting. Unsupported types (PDF, PowerPoint, images) return empty text with an
explanatory note, call traceable_library_index to persist supported text for search.

| Parameter | Type | Required | Meaning |
|---|---|---|---|
| `code_or_id` | `string` | **yes** | The item's REF code (e.g. REF-00001A) or its UUID |


#### `traceable_library_index`

_**Write access.** Only adds things, safe to ask for twice. Fetches from the web, so it reaches outside Traceable._

Extract and persist the plain text of a Reference Library item (identified by its REF code or id)
so it becomes searchable via traceable_library_search and cheap to read. Text extraction runs
locally (docx, spreadsheets, CSV, and text/markup formats; webpage items are fetched). Returns the
number of characters indexed, or unsupported=true for types this slice cannot extract (PDF,
PowerPoint, images).

| Parameter | Type | Required | Meaning |
|---|---|---|---|
| `code_or_id` | `string` | **yes** | The item's REF code (e.g. REF-00001A) or its UUID |


#### `traceable_library_add_reference`

_**Write access.** Only adds things, safe to ask for twice._

Attach a Reference Library item, or another document, to this document's reference list, and
ensure a Reference Table row exists to display it (created at the end of the body if absent). Pass
code_or_id (a library item's REF code e.g. REF-00001A, or its id, from traceable_library_search)
OR targetDocumentId (a document to cite), exactly one. The referenced version defaults to the
target's current/published version; override with referencedVersion. Idempotent: re-adding an
existing reference succeeds without duplicating it.

| Parameter | Type | Required | Meaning |
|---|---|---|---|
| `documentId` | UUID | **yes** | The document to add the reference to |
| `code_or_id` | `string` | no | Reference Library item REF code (e.g. REF-00001A) or its UUID |
| `targetDocumentId` | UUID | no | Instead of a library item, cite another document by its UUID |
| `referencedVersion` | `number` | no | Pin a specific version (default: the target's current/published version) |


### Capabilities

What the format itself supports.


#### `traceable_capabilities`

_**Read access.** Changes nothing, safe to ask for twice._

The Traceable Markdown (TrMD) format spec and capabilities manifest: row types, block directives,
layout directives, segments, property tokens, and paper sizes. Read this before reading or
authoring documents.

_Takes no parameters._

---

## 12. Where to get help

- In-app: **Help** (guides and search), or the **Support** menu to ask a question.
- Org admins control MCP access and the AI change review setting.