MCP connector 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:
- 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.
- 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:
- The organisation must permit external agents at all. This is on by default, so nothing changed for organisations that already had the connector working.
- 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)
- Open Settings → Connectors.
- Choose Add custom connector.
- Paste the address above and save.
- Claude sends you to Traceable's sign-in and then to a consent screen headed "Authorize … wants to connect to your Traceable account".
- Check the permissions listed, then approve.
In Claude Code
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:
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.
See Traceable on your own documents
Import your existing requirements and see live traceability in minutes.