# Working with an AI assistant (MCP)

Category: AI and integrations
Last updated: 2026-09-03
Canonical: https://traceabledocs.com/docs/ai-assistant-mcp

## Working with an AI assistant (MCP)

The Traceable MCP connector lets an AI assistant (Claude on claude.ai, Claude Desktop, or Claude Code) work inside your account the way you do: browse projects, read documents, draft and edit content, build ID grids, create trace links, and search the Reference Library.

Two things govern everything else:

1. **It acts as you.** It signs in with your account through a consent screen and can reach exactly what you can reach. Not a member of a project? Neither is the assistant. Read-only role? The assistant is read-only too.
2. **It only touches drafts.** Publishing, review, and e-signature stay human actions in the app. Every change is written to the audit log against your name, and each edited row waits for you in the document's **Agent** panel.

### Before you connect

**MCP access is off by default.** An org admin turns it on for you in **Organisation → Members**, in the **AI / integrations access** box. That switch is also the instant cut-off: turning it off disconnects the connector straight away.

### Connecting

The server address is `https://app.traceabledocs.com/api/mcp/mcp`.

- **claude.ai (web, desktop, mobile):** **Settings → Connectors → Add custom connector**, paste the address, then sign in to Traceable and approve the consent screen.
- **Claude Code:** run `claude mcp add --transport http traceable https://app.traceabledocs.com/api/mcp/mcp`, then follow the sign-in prompt the first time a Traceable tool is used.

The consent screen asks for two permissions: **Read your projects and documents**, and **Create and edit document content**.

### What it can do

- **Explore:** list your organisations and projects, map a project's groups, documents and headings, show the trace link graph between documents, list templates, and read a document as an outline or in full.
- **Author:** create a document (optionally from a template), insert or replace blocks, replace a whole segment, delete a block, and update document metadata including heading auto-numbering.
- **ID grids:** add a column, rename a column header, change a column's type (including dropdown options and calculation sources), and set a single cell. These edit in place and keep every row's trace links intact. Summary columns stay app-only.
- **Traceability:** create and delete trace links, rename a TraceID in place without breaking its links, and re-prefix a whole document's TraceIDs.
- **Reference Library:** list, index, search and read items you can access, and cite an item or another document on a document.

Ask in plain language, and name things precisely: document numbers (TD01-003), TraceIDs (FR-012), and REF codes (REF-00001A) remove the guesswork. For example: *"Read TD01-002 and list every user need with no downstream requirement."*

### What it cannot do

Publishing, reviews, approvals and e-signature. Creating projects, organisations or users. Uploading images or attachments. Deleting a live document (only an **archived** one can be deleted, and that is permanent). Reading PDFs, PowerPoint or images in the Reference Library.

### What happens to your documents

A write to a **published** document opens a **new draft** first, and the published version stays intact in history. Edits get their own line on the **Versions** timeline, like one of your own editing sessions.

While a project has **Require AI change review** on (Organisation → Projects, admin only, on by default), every row an assistant writes appears in the document's **Agent** panel under **Pending** for a contributor or admin to **Acknowledge**. Block deletions are soft and recoverable, and links to a deleted row are marked broken rather than vanishing.

> Prefer targeted edits to wholesale rewrites. Replacing a whole segment soft-deletes its rows and breaks links to them, so ask to "update FR-012" or "add a column to that grid" instead.

### Managing access

**Account → Connected apps** lists every app you have authorised and lets you revoke one. Revoking stops it obtaining new access; access it already holds stops working within the hour. Admins can also revoke a member's connection from **Organisation → Members**.

If the connector suddenly stops working, reconnect: it is served by the app itself, so it drops briefly on every deployment.