MCP tools

Workstate has two MCP servers. rag-corpus searches the index. rag-ledger reads and writes the ledger. This page lists every tool on each, with its parameters and what it returns.

How every tool behaves

• The namespace comes from the connection, not from the tool. No tool takes a namespace argument. Each call uses the namespace in the X-RAG-Namespace header, or your oldest namespace when there is none. The header is checked against your key.
• The author is the key's owner. Every ledger write is recorded as the person whose API key made the call. The agent's name comes from the tool's agent argument, or else from the X-RAG-Agent header.
• Results are JSON. Each tool returns its result as text that holds JSON.
• Errors say what to fix. For example, forbidden: no grant for namespace "ws-…" means your key cannot reach that namespace, and forbidden: principal has no workspace grants means you have not been given any namespace yet. A missing or revoked key fails before any tool runs, with HTTP 401.

rag-corpus

Address: https://mcp-uat.workstate.io/corpus

search_corpus

Searches the namespace's index: code, documents and the ledger. It returns the best-matching passages, reranked, each with where it came from.

Parameter	Type	Required	Meaning
query	string	Yes	What to find, in plain words: a concept, a name, a behaviour. Must not be empty.
top_k	integer	No	How many results to return. The default is 8. Search ranks the best 50 candidates, so it never returns more than 50.
rerank	boolean	No	Whether to rerank the candidates for quality. The default is true. Set it to false only for debugging.
corpus	string	No	Search only code, wiki or ledger.
repo	string, or array of strings	No	Search one repository by its exact name, or several, such as ["api", "web"].
language	string	No	Search one language, such as rust, python or markdown.
path_prefix	string	No	Only files whose path starts with this, such as docs/. It is applied after the candidates are chosen, so a narrow prefix can return fewer results than top_k.

Returns the query, the top_k used, whether the results were reranked, and results. Each result has:

Field	Meaning
repo	The repository the passage came from.
rel_path	The file's path in the repository.
start_line, end_line	The lines the passage covers.
text	The passage.
corpus, language	The corpus and the detected language.
ann_score, rerank_score	How close the passage was in the first pass, and its relevance after reranking.
topic_id, type, status	Ledger results only: the topic, its type and its status.

Cite a result as repo/rel_path:start_line-end_line. Ignore the path field, which is Workstate's internal location for the file. Other fields, such as timings, may also appear.

reindex_corpus

Queues a sync of every GitHub, Confluence and Jira source in the namespace, for changes you want searchable now. It returns once the syncs are queued. Syncs usually finish within a few minutes, and unchanged files are skipped.

Anyone with access to the namespace can call it.

Parameter	Type	Required	Meaning
None

It leaves these sources alone, and says why:

Reason	Meaning
upload	An upload source changes only when someone uploads files, and each upload syncs it.
paused	Someone paused the source.
cancelling	Someone is stopping the source's sync, which leaves it paused.
deleting	The source is being deleted.

Returns the namespace, how many syncs were queued, and sources: each source's source_id, label and kind, with an outcome of queued or skipped. A queued source has a job_id, and created is false when a sync was already on its way. Another sync then follows it, so no change is missed. A skipped source has a reason.

rag-ledger

Address: https://mcp-uat.workstate.io/ledger

ledger_search

Searches the ledger by meaning, to find earlier decisions, incidents, defects and investigations. A topic appears at most once in the results.

Parameter	Type	Required	Meaning
query	string	Yes, unless archived is true	What to look for, such as "have we decided this before?".
top_k	integer	No	How many results. The default is 8.
repo	string, or array of strings	No	Only topics filed under this project, or these projects.
type	string	No	decision, incident, defect or investigation.
status	string	No	open, proposed, accepted, resolved, superseded, reverted or wontfix.
archived	boolean	No	Set to true to search archived topics instead. That search matches the words you give, not their meaning, and returns up to 50 topics by default. Archived topics never appear in a normal search.

Returns matching topics, best first. Each has its topic_id, type and status, the passage that matched, and, where available, its title, summary and when it was last updated (updated_at). Read a topic in full with ledger_get.

ledger_get

Fetches one topic with its complete record. It works for archived topics too.

Parameter	Type	Required	Meaning
topic_id	string	Yes	The topic's id, such as payments-0012.

Returns the topic: its topic_id, type, repo, title, fixed summary, current_state and status; who created it and when (creator_email, creator_agent, created_at) and when it was last updated (updated_at); its tags; whether it is archived; its full history as events; and links to the topics it supersedes or is superseded by. Each event has its time (ts), its author (author_email, author_agent), its kind and body, and any new state or status it set.

If the topic was moved to another project, it returns a pointer instead, {"moved": true, "moved_to": "<new id>", …}. Fetch the new id.

If there is no such topic in the namespace, it returns ledger topic … not found.

ledger_create

Opens a new topic for one decision, incident, defect or investigation. Create one topic per decision or finding, even when you make several in one task.

Parameter	Type	Required	Meaning
type	string	Yes	decision, incident, defect or investigation.
title	string	Yes	A one-line title.
summary	string	Yes	The original framing of the decision, bug or incident. It never changes.
initial_state	string	Yes	Where the topic stands now, in brief. It becomes the first entry in the history.
repo	string	Yes, on Workstate	The project to file the topic under, such as a repository's name. It can use letters, digits, dots, hyphens and underscores, and it becomes the start of the topic's id.
status	string	No	The starting status. The default is proposed for a decision, and open for the other types.
tags	array of strings	No	Tags for the topic.
agent	string	No	The agent's name, such as "Claude Code". Without it, the X-RAG-Agent header is used.

Returns the new topic, including its topic_id, such as payments-0012: the project name, then a number that counts up within that project. ledger_get finds a new topic at once. Search finds it shortly after it is written.

If repo is missing, it returns repo not given and could not be inferred from a git repo.

ledger_append

Adds an entry to a topic's history, to move that same topic on: a change of state or status, a correction, or the outcome. A new, separate decision or finding belongs in a new topic, made with ledger_create.

Parameter	Type	Required	Meaning
topic_id	string	Yes	The topic to add to.
body	string	Yes	What happened, what was learned, or what changed.
kind	string	No	The kind of entry: note (the default), state_change, status_change or correction.
set_state	string	No	The topic's new current state. Keep it a short status, not a growing report.
set_status	string	No	The topic's new status, such as accepted, resolved or reverted.
supersedes	string	No	The id of an older topic that this topic replaces. It links the two both ways, and marks the older topic superseded. The older topic must be in the same namespace.
agent	string	No	The agent's name. Without it, the X-RAG-Agent header is used.

Returns the new history entry: its event_id, time (ts), author, kind, body, and any new state or status.

History is append-only. No tool edits or deletes an entry. If the topic was moved, it returns topic … was moved to …; append to that id instead.

ledger_move

Refiles a topic under another project. The topic gets a new id in that project, with a new number. Its whole history and its links move with it, and an entry in the history records the move.

Parameter	Type	Required	Meaning
topic_id	string	Yes	The topic to move.
repo	string	Yes	The project to move it to.
agent	string	No	The agent's name. Without it, the X-RAG-Agent header is used.

Returns the topic under its new id. The old id no longer names a topic: ledger_get on it returns a pointer to the new id.

ledger_archive

Archives a topic, or restores an archived one. Archiving is a soft delete, for noise or obsolete topics. An archived topic keeps its history, but it disappears from ledger_search and from search_corpus. ledger_get still fetches it, and ledger_search with archived: true finds it.

Parameter	Type	Required	Meaning
topic_id	string	Yes	The topic to archive or restore.
archived	boolean	No	true, the default, archives the topic. false restores it.
agent	string	No	The agent's name. Without it, the X-RAG-Agent header is used.

Returns the topic, with its archived state.

Related

• Agents & clients
• Agent instructions
• The ledger
• Search & citations