Quickstart
This page takes you from your trial invite to an answer your agent cites from your own tenant, which is your team's private space in Retiform. It uses Claude Code. Where VS Code agent mode differs, a note says how. Each step says what you should see. If you see something else, the step's note says where to look.
Before you start
- The address you were invited with. If your invitation came from a tenant's administrator, its email
has the sign-up link. Otherwise sign up at the trial's console,
api.retiform.ai/console/. Once you are in, the console's Connect your agent panel shows your MCP address, which ends in/mcp, and the exact command to add it. - Claude Code, or VS Code with agent mode and MCP support turned on.
- The sample corpus, downloaded and unzipped into an empty folder. It holds
ten documents and a
README.mdabout the corpus and its licence, which you don't upload.
1. Sign up
Open the sign-up link, or the console, and enter the invited email address. Confirm the address from the message Retiform sends, read and accept the trial terms, and name your tenant.
You should see your tenant's status. If activation waits for the next batch of new tenants, the page says when to expect it, and Retiform emails you once the tenant is active.
If this differs: sign-up only accepts the address the invite was sent to. A different address gets the same neutral answer as an unknown one, so check which address you used.
2. Connect Claude Code
Add Retiform as an MCP server. The console's Connect your agent panel shows the command with your MCP address and your tenant filled in, ready to copy:
claude mcp add --transport http retiform-<your tenant> <your MCP address>
The server is named after your tenant's identifier (for example retiform-t-k2x9q4m7pz1a), so it stays apart from any other
Retiform server your agent has: another tenant's, or the Retiform plugin's. When it connects, the server
also tells the agent which tenant it is.
Start Claude Code, run /mcp, choose retiform-<your tenant> and authenticate. Your browser opens, and three things
happen there:
- Sign in. Enter the email address from step 1. There is no password: Retiform emails you a code, and you enter it. The code can take a minute to arrive.
- Approve the agent in Retiform's console. The console names the agent client that is asking and lists what it may do. Tick what you want to allow and approve. For this quickstart the agent needs to read and to write.
- Confirm on the sign-in screen that follows. It lists the same permissions once more. Accept, then go back to Claude Code.
You should see retiform-<your tenant> connected in /mcp, with its tools listed: among them
upload_document, assemble_context, read_passage and record_memory. No API key or other
configuration is needed.
If this differs: if no code arrives, check the address you typed and your spam folder, then ask for
another. Tools that need a scope you weren't granted fail with INSUFFICIENT_SCOPE.
Make sure you approved the client in your browser, and that you signed in to the tenant from step 1.
If you already use Retiform with another account: your browser signs you in as that account
without asking, and the agent then reads that tenant. The approval page names the tenant
("Allow an agent to use …"), so check it before you allow. To connect a different account, add
that tenant's server, under its own name from that tenant's Connect your agent panel, in a new
folder, and when /mcp authenticates, open the sign-in link Claude Code prints in a private browser
window signed in as that account. Do every sign-in step in that window.
In VS Code: run MCP: Add Server from the Command Palette, choose HTTP, enter the MCP
address and name the server retiform-<your tenant>, as the console's panel does. VS Code saves it in .vscode/mcp.json. Start the server and
sign in when VS Code asks. Then open Chat in agent mode and check that Retiform's tools are listed
under the tools button.
3. Load the sample corpus
In Retiform's console, where you signed up, open Documents and choose Choose files. Select
the ten documents in the corpus folder, every file except README.md, and choose Send 10 files.
The files go straight to Retiform, not through your agent.
You should see each file marked added, then searchable once Retiform has processed it.
Processing a document takes a few seconds to a minute. The ten documents are then listed under
Your documents.
If this differs: each file says what happened to it. A file over the trial's size limit is
skipped: too large, and a full tenant stops the upload with The documents limit is reached.
None of the sample documents is near either limit. A file marked processing failed can be sent again.
How documents are named. Files you choose one by one are named by their file names. A folder
you choose or drop is named by the folder's name and each file's path inside it, such as
corpus/adr-001-postgresql-booking-store.md. The console and the kg command follow the same
rule. Sending the same files again the same way doesn't add new documents: a file whose text hasn't
changed is marked unchanged, and a changed file becomes a new revision of its document. Sending
them once as files and once as a folder gives two sets of documents, so pick one way for the corpus.
If you choose or drop the corpus folder, move its README.md out of the folder first, or it is sent too.
For a large folder of your own, the kg command sends a whole folder from a terminal with the
same rules as the console. It needs Node.js 22 or later:
npx @retiform-ai/kg upload ./my-folder
The first run shows an address and a code. Open the address, check the code and sign in as in
step 1. Before sending, kg names your tenant, your account and the platform, and asks you to confirm:
answer y. kg sends every file in the folder except hidden ones. To send the sample corpus this way
instead of with Choose files, move its README.md out of the folder first. The documents are
then named by the folder's name and their file names, as above. kg reports each file as added
once Retiform has stored it, and doesn't wait for processing: the console's Documents page shows
when each document is searchable, usually within a minute.
From your agent: keep upload_document for one short document that your agent writes itself,
such as a summary it has just drafted, and follow its processing with get_document_job. Don't use
it to load files you already have. The agent retypes each file's text into the request, which is
slow for more than a few files, and nothing compares what it sends with the file, so a mistake in
retyping goes unnoticed. Send files with the console or kg upload, which read them directly.
4. Ask a question
Ask your agent:
Using Retiform, why was PostgreSQL chosen for Ferrylog's bookings? Cite your sources.
You should see the agent call assemble_context, then answer from passages of ADR-001, "PostgreSQL as the
booking store", each with a citation: the document's identifier (doc_…), its revision and the passage's ordinal.
Claude Code folds its tool calls into one line, such as "Called retiform-… 2 times"; press Ctrl+O to see them.
If this differs: if the answer cites nothing, check that step 3 finished. A document's passages can be searched by keyword as soon as they're stored, and by meaning once they're embedded.
5. Open a cited passage
Ask your agent:
Use
read_passageto show me the exact text of the first passage you cited.
You should see the passage's text and its citation, the same text the answer relied on.
current is true while the document hasn't been revised since.
6. Record and correct a memory
ADR-003 says payment logs are kept for 30 days; a later follow-up changed that to 13 months. Record the old rule first, then correct it. Ask your agent:
Record in Retiform's memory only what ADR-003 itself says about how long payment logs are kept, citing only ADR-003. I know it is out of date: we will correct it next.
Then ask:
Supersede that memory with the corrected retention from the follow-up, citing the follow-up. Then show me the memory's history.
You should see two versions, oldest first. The first is marked superseded and still has its
original statement and its ADR-003 citation; the second is current and cites the follow-up. Each
version shows who wrote it and when.
What next
- Shared decisions in Claude Code: install the Retiform plugin so that every session in a repository starts with your team's decisions.
- Concepts explains what a citation points at, and what superseding a memory keeps.
- The sample corpus page lists more questions, each answered by specific sentences in the documents.