Traceable MCP Server已验证已精选

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, 25 tools. Last updated: 2026-10-04

---

1. What this is

The Traceable 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 Org settings → Members, open the member, and in the AI / integrations access box switch Enable MCP access on.

For the whole organisation. Go to Org settings → AI agents and switch Allow external AI agents to connect (MCP) on.

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

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.

ChatGPT and Cursor have been connected and used end to end (verified 3 October 2026). VS Code and Gemini are expected to work because they speak the same protocol, but we have not yet run them end to end. If you connect one of those successfully, or hit a problem with any client, tell us through the in-app Support menu (section 12) so this list stays accurate.

Client	Where to put the URL	Status
ChatGPT	Developer mode, as a custom connector	Verified
Cursor	MCP settings, as an HTTP server	Verified
VS Code	MCP settings, as an HTTP server	Not yet verified
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.	Not yet verified

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: the connector serves the streamable HTTP transport only.

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 Org settings → AI 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 infusion pump 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, Test Plans, diagrams, page and section breaks (including paper size and orientation), and property tokens such as {{docTitle}}.

A test report places its Test Plan by name, for example [[test-plan plan="OQ Test Plan"]]. The plan must already exist in Project settings, because the assistant cannot create one. The row binds to the plan and its entries are created from the plan's source documents, just as choosing the plan in the editor does. A plan name that does not match, or an inactive plan, leaves the row unbound with a warning, and you choose the plan in the row.

Add columns= to choose what the row shows: a stage (plan, test, baseline), individual columns, or both, for example [[test-plan plan="OQ Test Plan" columns="links,test"]]. Protocol is always shown.

The assistant can also record the test itself. It reads a Test Plan row's entries, then fills in each entry's columns: the decision and rationale, the results, notes, samples, location and equipment, Pass/Fail, and the baseline assessment and resolution, per test step where the protocol has steps. It can attach evidence, either from the document's references or by uploading a file: an image shows inline in the Evidence column, and any other file is filed in the project's Reference Library and attached as a chip. One thing stays with a person: the tester's electronic signature, which the assistant cannot apply. Every change the assistant makes to a Test Plan goes to review like any other agent change.

"Create an OQ report from our report template and place the OQ Test Plan in its Executed Results section."

"Draft a 12-requirement Functional Requirements document from the user needs in PRJ-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 PRJ-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 PRJ-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 into document content	Images already in a document read back fine, but the assistant cannot add new ones to rows yet. Test Plan evidence is the exception: the assistant can upload it, up to 3 MB a file.
Signing a Test Plan entry as the tester	The tester's signature is an electronic signature (21 CFR Part 11). The assistant records results; the tester signs in the app.
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 (Org settings → Projects, admin only), on by default. On the Regulated plan an org admin can also require it in every project (Org settings → AI agents), and then no project can switch it off. While it is on, every row an assistant writes is flagged and appears on the Agent changes tab of the document's Review panel under Pending, with the row preview and its TraceID. Contributors and admins get an Acknowledge button, and acknowledged changes move to the Acknowledged list. The tab 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 (PRJ-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 PRJ-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 PRJ-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 PRJ-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

• Org settings → 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	Connections can drop briefly while Traceable is being updated. 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 25 tools: 8 need read access and 17 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. PRJ-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)

traceable_test_plan_read

Read access. Changes nothing.

Read a bound Test Plan row: the plan, the columns the row shows, and every entry with its protocol TraceID, protocol cells, all column values, its evidence, the tester signature (if signed) and, for a protocol with test steps, each step (numbered from 1) with its text, acceptance criteria and recorded result.

Parameter	Type	Required	Meaning
documentId	UUID	yes	The document holding the Test Plan row
row	{ itemId?, atOrder? }	yes	The Test Plan row, by TraceID or by its [[row N]] anchor

traceable_test_plan_entry

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

Record data in one Test Plan entry, as {column: value}. The entry's own columns are decision (include or exclude), rationale, result_text, test_notes, samples, location, equipment, result (pass, fail, or empty to clear), assessment, baseline_notes and resolution (passed, failed, passed_with_deviation, failure_accepted, or empty for the derived default). With step, the columns are that test step's result_text, notes and result. The same validation and limits apply as in the editor. The tester's signature cannot be applied, and the Test Plan row goes to review.

Parameter	Type	Required	Meaning
documentId	UUID	yes	The document holding the Test Plan row
row	{ itemId?, atOrder? }	yes	The Test Plan row
entry	{ entryId?, protocol? }	yes	The entry, by id or by its protocol TraceID
fields	{ column: value }	yes	The columns to write
step	number	no	A test step, numbered from 1; omit for the entry's own columns

traceable_test_plan_evidence

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

Add or remove file evidence on a Test Plan entry, or on one of its test steps. The evidence is a Reference Library item the document references, named by REF code or item id; add the reference first with traceable_library_add_reference. It shows as a chip labelled in the document's citation format. To upload a new image or file, see traceable_test_plan_evidence_upload. The Test Plan row goes to review.

Parameter	Type	Required	Meaning
documentId	UUID	yes	The document holding the Test Plan row
row	{ itemId?, atOrder? }	yes	The Test Plan row
entry	{ entryId?, protocol? }	yes	The entry
op	add | remove	yes	Add or remove the evidence
reference	string	yes	The Reference Library item's REF code or UUID
step	number	no	A test step, numbered from 1; omit for the entry's own evidence

traceable_test_plan_evidence_upload

Write access. Adds things without overwriting, asking twice does it twice.

Upload a file as evidence on a Test Plan entry, or on one of its test steps. The file travels as base64 with its name. An image (PNG, JPEG, GIF or WebP, recognised from the file itself rather than its name) is shown inline in the Evidence column, exactly as an upload in the editor is. Any other file type is added to the project's Reference Library, referenced by the document, and attached as a file chip labelled in the document's citation format. At most 3 MB per file, because that is the largest request the server accepts once base64 has added its third. The Test Plan row goes to review.

Parameter	Type	Required	Meaning
documentId	UUID	yes	The document holding the Test Plan row
row	{ itemId?, atOrder? }	yes	The Test Plan row
entry	{ entryId?, protocol? }	yes	The entry
name	string	yes	The file name
content	string	yes	The file, base64-encoded
step	number	no	A test step, numbered from 1; omit for the entry's own evidence

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: 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.