MCP Tools Reference

Parameter-level reference for the 19 public MCP tools across 6 categories: Capture, Extraction, Custom Skills, Discovery, Research, Annotate. Every tool returns cited results — each claim traces back to a source and character range in the original content.

Scope of this reference. These are the 19 starter MCP tools — the public surface for capture, extraction, search, research, and annotation. Multiplist also exposes workspace & operator tools (containers, studios, lanes, cards, routing) and advanced intelligence tools (refinement, deliverable production) that aren't documented here yet. Start with the 19 below — they cover the lifecycle most agents need.

Auth prereq: Tool calls go to https://multiplist.ai/mcp and require either an MCP Token (prefix mcp_live_, sent as the x-mcp-key header) or an OAuth 2.1 access token. See Authentication for setup. REST API Keys (prefix mp_live_) are a different system and will not work here.

# 1. Capture

Save conversations, documents, and notes to your vault. Updates are incremental — only new content is extracted on subsequent saves.

# `create_source`

Save a conversation, document, or note to the vault. Optionally triggers extraction immediately.

Scope: sources:write

Parameter	Type	Required	Description
`title`	string (1–500)	yes	Source title.
`content`	string (1–512000)	yes	Full source content. Max 500KB.
`sourceType`	enum	no	Source type classification. Default: `mcp`.
`platform`	string (max 100)	no	Platform or origin label.
`tags`	array (max 20)	no	Tags to attach to the source.
`externalId`	string (max 500)	no	External system identifier for dedup.
`skipDedup`	boolean	no	Skip deduplication check.
`autoExtract`	boolean	no	Trigger extraction immediately. Default: `true`.
`skillId`	string (uuid)	no	Specific skill to use for extraction.
`categories`	array of extractionCategory	no	Limit auto-extraction to specific categories.
`abstract`	boolean	no	Generate an abstract. Default: `true`.

# `update_source`

Update a saved conversation with new content. Append mode (default) adds content to the end; replace mode overwrites fully. Only new content is re-extracted.

Scope: sources:write

Parameter	Type	Required	Description
`sourceId`	string (uuid)	yes	Source to update.
`title`	string (max 500)	no	New title.
`content`	string (max 512000)	no	Content to add or replace. Max 500KB.
`mode`	enum `["append","replace"]`	no	`append` (default) adds to end of existing source. `replace` overwrites the full content.
`reExtract`	boolean	no	Extract meaning from new content after update. Incremental — only processes content added since last extraction. Default: `true`.

# `delete_source`

Remove a source and all seeds extracted from it.

Scope: sources:write

Parameter	Type	Required	Description
`sourceId`	string (uuid)	yes	Source to delete.

# 2. Extraction

Run the semantic extraction engine on sources to produce cited seeds across eight meaning categories. Single-source or batch.

# `trigger_extraction`

Run extraction on a single source. Produces seeds categorized across decisions, frameworks, golden passages, definitions, actions, questions, offers, and emergence.

Scope: extract:run

Parameter	Type	Required	Description
`sourceId`	string (uuid)	yes	The source to extract from.
`skillId`	string (uuid)	no	Specific skill to apply. System matches automatically if omitted.
`categories`	array of extractionCategory	no	Limit extraction to specific categories.

# `batch_extract`

Start extraction across multiple sources. Runs asynchronously; poll with batch_status.

Scope: sources:write

Parameter	Type	Required	Description
`sourceIds`	array (1–50)	yes	Source IDs to extract from.
`containerId`	string (uuid)	no	Container context for skill matching.
`categories`	array of extractionCategory	no	Limit extraction to specific categories.

# `batch_status`

Poll the status of a batch extraction job — sources processed, seeds created, errors.

Scope: seeds:read

Parameter	Type	Required	Description
`jobId`	string (uuid)	yes	The batch job ID returned by `batch_extract`.

# 3. Custom Skills

Skills tell Multiplist what to look for in your content. A coach creates "Client Breakthroughs." A developer creates "Architecture Signals." Skills make extraction domain-aware.

# `create_skill`

Create a custom extraction skill with its own schema, instructions, and trigger conditions.

Scope: skills:write

Parameter	Type	Required	Description
`name`	string (1–200)	yes	Skill name.
`description`	string (max 2000)	no	Human-readable description.
`domain`	string (max 100)	no	Domain label (e.g. research, engineering, design).
`instructions`	string (1–50000)	yes	Full extraction instructions for the model.
`schema`	array of `{ field, type, description, enumValues? }` (max 20)	no	Structured output schema.
`triggerConditions`	object	no	Conditions for automatic skill matching.
`parentSkillId`	string (uuid)	no	Parent skill for inheritance.

# `list_skills`

List all extraction skills in your vault.

Scope: skills:read

Parameter	Type	Required	Description
`domain`	string (max 100)	no	Filter by domain.
`containerId`	string (uuid)	no	Filter by container.
`search`	string (max 200)	no	Search skills by name or description.

# `get_skill`

Fetch a single skill's full instructions and schema.

Scope: skills:read

Parameter	Type	Required	Description
`skillId`	string (uuid)	yes	The skill to retrieve.

# `match_skills`

Find which skills apply to a given source based on content and trigger conditions.

Scope: skills:read

Parameter	Type	Required	Description
`sourceId`	string (uuid)	yes	The source to match against.
`containerId`	string (uuid)	no	Limit matching to skills in this container.

# 4. Discovery

Search and retrieve across your vault. Every result cites its source with exact character positions in the original content. Use search_vault to query meaning across all sources; search_sources to browse by metadata; get_source to pull a specific source back with its full Seed Doc.

# `get_source`

Retrieve a full source with its abstract, seeds grouped by category, and assets. The Seed Doc. Returns all seeds: the 8 canonical categories (decisions, frameworks, golden passages, definitions, actions, questions, offers, emergence) plus any custom skill categories (e.g. "Product Moves", "Architecture Signals") from skill extractions. Use this tool to browse skill extraction results — custom skill seeds are grouped under their skill field names alongside the canonical sections.

Scope: seeds:read

Parameter	Type	Required	Description
`sourceId`	string (uuid)	no	Source ID. Provide `sourceId` or `title`.
`title`	string (max 500)	no	Source title to look up.
`include`	array of enum `["abstract","seeds","assets","content"]`	no	Which sections to include.
`categories`	array of extractionCategory	no	Filter returned seeds to specific canonical categories. Custom skill category seeds are always included when `seeds` is requested.
`format`	enum `["document","json"]`	no	Response format. Default: `document`.

# `search_vault`

Search across all saved sources for seeds matching a query. Returns cited results with exact provenance. Searches seed content across all seeds (canonical and skill). The category filter accepts the 8 canonical extraction categories AND any skill-defined category name — it matches both the stored form (e.g. product_moves) and the human-readable form (Product Moves).

Scope: recall:search

Parameter	Type	Required	Description
`query`	string (1–1000)	yes	Search query text.
`category`	string	no	Filter by extraction category. Accepts canonical categories (`decision`, `framework`, `golden_passage`, `definition`, `action`, `question`, `offer`, `emergence`) or any skill-defined category name.
`temperature`	enum `["hot","warm","cold","all"]`	no	Filter by recency: hot (7d), warm (7–30d), cold (30d+).
`limit`	number (1–50)	no	Max results. Default: 20.

# `search_sources`

Browse sources by title, date, type, or keyword. The card catalog of your vault.

Scope: recall:search

Parameter	Type	Required	Description
`query`	string (max 1000)	no	Keyword search across source titles and content.
`sourceType`	string	no	Filter by source type.
`dateRange`	object `{ after?, before? }`	no	ISO date range filter.
`extractionStatus`	enum `["complete","partial","unmapped","extracting","error"]`	no	Filter by extraction status.
`sortBy`	enum `["recent","seeds","relevance"]`	no	Sort order. Default: `recent`.
`limit`	number (1–50)	no	Max results. Default: 10.

# `get_vault_summary`

High-level snapshot of the vault: source count, seed count, category distribution, recent activity, topic clusters.

Scope: seeds:read

Parameter	Type	Required	Description
`includeRecent`	number (0–20)	no	Number of recent sources to include. Default: 5.
`includeTopics`	boolean	no	Include topic cluster analysis. Default: `true`.

# `get_vault_gaps`

Analyze vault coverage — sparse categories, unextracted sources, under-represented areas.

Scope: seeds:read

Parameter	Type	Required	Description
`studioId`	string (uuid)	no	Narrow analysis to a specific studio.

# 5. Research

Synthesize across your entire vault. Research briefs trace the evolution of your thinking on a topic, with citations to every source used.

# `request_brief`

Synthesize a research brief across vault sources on a topic. Two modes: full (default) runs async and saves the result as a vault source; retrieval_only returns synchronously with ranked seeds and no vault write.

Scope: recall:search

Parameter	Type	Required	Description
`topic`	string (1–2000)	yes	The research topic or question.
`focusQuestions`	array of strings (max 10)	no	Specific questions to address.
`sourceScope`	object `{ dateRange?, sourceIds?, categories? }`	no	Narrow the sources considered.
`depth`	enum `["quick","standard","deep"]`	no	Research depth. Default: `standard`.
`briefType`	enum `["research","evolution","constellation","status"]`	no	Type of brief. Default: `research`.
`mode`	enum `["full","retrieval_only"]`	no	`full` (default): async LLM synthesis, saves as vault source, returns `sourceId` to poll. `retrieval_only`: synchronous, returns ranked seeds + constellation links, no LLM generation, no vault write.

# `get_brief_status`

Poll the status of a research brief. Accepts sourceId (preferred — returned by request_brief) or briefId (legacy). Status values: synthesizing, complete, error.

Scope: seeds:read

Parameter	Type	Required	Description
`sourceId`	string (uuid)	no	Source ID returned by `request_brief` (preferred).
`briefId`	string (uuid)	no	Brief ID — legacy path for briefs pre-dating the brief-as-source collapse.

# 6. Annotate

Write corrections, evolution notes, and commentary back to your sources. Annotations preserve who made the mark and what kind of mark it is — a correction, a tension, an evolution narrative, or additive commentary.

# `add_annotation`

Attach an author annotation to a source. For the source's own author to mark decisions, insights, or notes while working on it.

Scope: sources:write

Parameter	Type	Required	Description
`sourceId`	string (uuid)	yes	The source being annotated by its own author.
`content`	string (1–50000)	yes	The annotation content.
`title`	string (1–500)	yes	Brief title for the annotation.
`scribe`	object `{ type, identifier }`	yes	Who is making the mark. Must match the source's author.
`intent`	extractionCategory	no	Underlying meaning category (decision, framework, etc.).
`confidence`	enum `["high","medium","low"]`	no	Confidence level. Default: `medium`.
`sessionContext`	string (max 1000)	no	Brief description of the conversation context.

# `add_marginalia`

Add a later-mind mark to a source — correction, tension flag, evolution narrative, or commentary.

Scope: sources:write

Parameter	Type	Required	Description
`sourceId`	string (uuid)	yes	The source being marked.
`markType`	enum `["correction","tension","evolution","commentary"]`	yes	Speech act of the mark.
`content`	string (1–50000)	yes	The marginalia content.
`title`	string (1–500)	yes	Brief title for the mark.
`scribe`	object `{ type, identifier }`	yes	Who is making the mark — `type` is `ai` or `human`.
`intent`	extractionCategory	no	Optional underlying meaning category.
`relatedSeedIds`	array (max 20)	no	Other seeds involved in the mark.
`relatedSourceIds`	array (max 20)	no	Other sources involved (for evolution chains).
`severity`	enum `["low","medium","high"]`	no	For tension marks — helps users triage.
`supersededBy`	string (uuid)	no	For correction marks — points to the newer canonical source or seed.
`sessionContext`	string (max 1000)	no	Brief description of the conversation context.

MCP Tools Reference

# 1. Capture

# create_source

# update_source

# delete_source

# 2. Extraction

# trigger_extraction

# batch_extract

# batch_status

# 3. Custom Skills

# create_skill

# list_skills

# get_skill

# match_skills

# 4. Discovery

# get_source

# search_vault

# search_sources

# get_vault_summary

# get_vault_gaps

# 5. Research

# request_brief

# get_brief_status

# 6. Annotate

# add_annotation

# add_marginalia

# `create_source`

# `update_source`

# `delete_source`

# `trigger_extraction`

# `batch_extract`

# `batch_status`

# `create_skill`

# `list_skills`

# `get_skill`

# `match_skills`

# `get_source`

# `search_vault`

# `search_sources`

# `get_vault_summary`

# `get_vault_gaps`

# `request_brief`

# `get_brief_status`

# `add_annotation`

# `add_marginalia`