> ## Documentation index > Fetch the complete documentation index at: https://contextrepo.com/docs/llms.txt > Use it to find every page before exploring further. # Tools Reference > Reference for the current hosted MCP tools, with parameters, types, and usage examples organized by category. This page documents every tool available through the Context Repo MCP Server. Each tool listing includes its exact parameters, types, and a brief usage example. All tools require authentication. If you haven't connected your AI assistant yet, see the [setup guides](https://contextrepo.com/docs/mcp/setup-guides/cursor) to get started. > **Note:** Parameters marked **Required** must be provided. Optional parameters can be omitted — the server uses sensible defaults. > **Note:** This reference describes the hosted `https://contextrepo.com/mcp` tool > contract. The `context-repo-mcp` v3 stdio package bridges to that endpoint, so > the same tool schemas, output shapes, `content`, and `structuredContent` pass > through without a separate package implementation. ## User Info ### get\_user\_info Get your Context Repo account details including name, email, and profile image. **Parameters** None. **Example Usage** > "What's my Context Repo account info?" Returns your user ID, first name, last name, email address, and profile image URL. --- ## Prompts ### search\_prompts List one page of prompts in your workspace. The optional search value filters that fetched page by title or description only. Use `find_items` for semantic search or literal prompt-body matching. **Parameters** | Parameter | Type | Required | Description | | --------- | ---------- | -------- | ------------------------------------------------------------- | | `search` | `string` | No | Filter prompts by title or description | | `limit` | `number` | No | Maximum number of prompts to return (default: 20) | | `cursor` | `string` | No | Opaque cursor from a previous response to fetch the next page | | `tags` | `string[]` | No | Tag filter (AND-semantics: all supplied tags must match) | **Example Usage** > "List my prompts about code review" Returns each prompt's title, description, public/private status, current version, and ID, plus pagination metadata. If `hasMore` is true, pass the returned cursor to the next `search_prompts` call. --- ### read\_prompt Get the full content of a specific prompt including its template variables. **Parameters** | Parameter | Type | Required | Description | | ---------- | -------- | -------- | --------------------------------------- | | `promptId` | `string` | Yes | The unique ID of the prompt to retrieve | **Example Usage** > "Show me the details of prompt abc123" Returns the prompt's title, description, version number, public/private status, full content, and any `${variables}` defined in the template. --- ### create\_prompt Create a new prompt template. You can include variables using `${variableName}` syntax in the content. **Parameters** | Parameter | Type | Required | Description | | ------------- | ---------- | -------- | ----------------------------------------------------------------- | | `title` | `string` | Yes | Title of the prompt | | `description` | `string` | Yes | Brief description of what the prompt does | | `content` | `string` | Yes | The prompt template content. Use `${variableName}` for variables. | | `tags` | `string[]` | No | Tags for categorizing the prompt | **Example Usage** > "Create a prompt called 'Bug Report Template' that asks for a summary, steps to reproduce, and expected behavior" Returns the new prompt's ID. --- ### update\_prompt Update an existing prompt. Only provide the fields you want to change — everything else stays the same. **Parameters** | Parameter | Type | Required | Description | | ------------- | ---------- | -------- | ------------------------------------------------------ | | `promptId` | `string` | Yes | The unique ID of the prompt to update | | `title` | `string` | No | New title | | `description` | `string` | No | New description | | `content` | `string` | No | New content | | `changeLog` | `string` | No | Description of what changed (saved in version history) | | `tags` | `string[]` | No | Replace tags (send `[]` to clear all tags) | **Example Usage** > "Update prompt abc123 to add a section about error handling, and note 'Added error handling section' in the changelog" Returns the updated prompt's title and new version number. --- ### delete\_prompt Permanently delete a prompt. This can't be undone. **Parameters** | Parameter | Type | Required | Description | | ---------- | -------- | -------- | ------------------------------------- | | `promptId` | `string` | Yes | The unique ID of the prompt to delete | **Example Usage** > "Delete prompt abc123" Returns a confirmation message. > **Warning:** Deletion is permanent. Make sure you don't need the prompt or its version history before deleting. --- ### get\_prompt\_versions View a prompt's version metadata, change logs, and content previews up to 200 characters. The list doesn't return full historical prompt bodies. **Parameters** | Parameter | Type | Required | Description | | ---------- | -------- | -------- | --------------------------- | | `promptId` | `string` | Yes | The unique ID of the prompt | **Example Usage** > "Show me the version history for prompt abc123" Returns each version's number, ID, author, change log entry, and a content preview. --- ### restore\_prompt\_version `restore_prompt_version` restores the selected version's content, parameters, and variables as a new version, so it doesn't overwrite history. Prompt title, description, tags, visibility, and other unversioned metadata remain at their current values. **Parameters** | Parameter | Type | Required | Description | | ----------- | -------- | -------- | ------------------------------------------------------------- | | `promptId` | `string` | Yes | The unique ID of the prompt | | `versionId` | `string` | Yes | The ID of the version to restore (from `get_prompt_versions`) | **Example Usage** > "Restore prompt abc123 to version xyz789" Returns the new version number after restoration. --- ## Documents ### list\_documents List one page of documents in your workspace with optional title filtering. **Parameters** | Parameter | Type | Required | Description | | --------- | ---------- | -------- | ------------------------------------------------------------- | | `search` | `string` | No | Filter documents by title | | `limit` | `number` | No | Maximum number of documents to return (default: 20) | | `cursor` | `string` | No | Opaque cursor from a previous response to fetch the next page | | `tags` | `string[]` | No | Tag filter (AND-semantics: all supplied tags must match) | **Example Usage** > "List my documents about machine learning" Returns each document's title, status, source type, creation date, and ID, plus pagination metadata. If `hasMore` is true, pass the returned cursor to the next `list_documents` call. --- ### get\_document Get document content up to the REST response limit. Use `deep_search` for targeted retrieval from large documents. **Parameters** | Parameter | Type | Required | Description | | ------------ | -------- | -------- | ----------------------------------------- | | `documentId` | `string` | Yes | The unique ID of the document to retrieve | **Example Usage** > "Show me document def456" Returns the document's title, status, source fields, canonical `revision`, `currentVersion`, `contentHash`, `lastChangedAt`, canonical application ETag, and content up to the REST response limit. --- ### create\_document Create a new text document with optional tags. **Parameters** | Parameter | Type | Required | Description | | --------- | ---------- | -------- | --------------------------------------------- | | `title` | `string` | Yes | Title of the document | | `content` | `string` | Yes | The document content (plain text or markdown) | | `tags` | `string[]` | No | Tags for categorizing the document | **Example Usage** > "Create a document called 'Meeting Notes - March 2026' with a summary of today's discussion, tagged with 'meetings' and 'engineering'" Returns the new document's ID and tags. --- ### update\_document MCP `update_document` and `restore_document_version` require `expectedRevision`, a nonnegative safe integer from `get_document` or the latest successful document acknowledgement. For restore, this is the current document revision, not the target historical version number. Each invocation makes exactly one REST write with `expectedRevision` in the body and no preflight GET. On `REVISION_MISMATCH`, call `get_document` again. If the intended state is already present, stop. Otherwise, reapply the change to the latest content and retry with the returned revision. Documents using `lease_required` managed editing must use the REST coordination workflow. MCP does not accept lease credentials. Update an existing document. Only provide the fields you want to change. **Parameters** | Parameter | Type | Required | Description | | ------------------ | ---------------- | -------- | ----------------------------------------------------------------------------------------------- | | `documentId` | `string` | Yes | The unique ID of the document to update | | `title` | `string` | No | New title | | `content` | `string` | No | New content | | `contentHtml` | `string \| null` | No | Replacement HTML, or `null` to clear it | | `rawHtml` | `string \| null` | No | Replacement raw HTML, or `null` to clear it | | `sourceUrl` | `string \| null` | No | Replacement source URL, or `null` to clear it | | `metadata` | `object` | No | Replacement validated metadata; send `{}` to clear | | `changeLog` | `string` | No | Description of what changed (saved in version history) | | `tags` | `string[]` | No | Replace tags (send `[]` to clear all tags) | | `expectedRevision` | `number` | Yes | Required current revision from `get_document` or the latest successful document acknowledgement | **Example Usage** > "Update document def456 with the revised introduction and log it as 'Rewrote introduction paragraph'" Returns a compact acknowledgement with the ID, canonical revision, content hash, change time, and `noop` status. Exact unchanged values don't create a version. --- ### delete\_document Permanently delete a document. This can't be undone. **Parameters** | Parameter | Type | Required | Description | | ------------ | -------- | -------- | --------------------------------------- | | `documentId` | `string` | Yes | The unique ID of the document to delete | **Example Usage** > "Delete document def456" Returns a confirmation message. > **Warning:** Deletion is permanent. Make sure you don't need the document or its version history before deleting. --- ### get\_document\_versions View a document's complete version history with change logs. **Parameters** | Parameter | Type | Required | Description | | ------------ | -------- | -------- | ----------------------------- | | `documentId` | `string` | Yes | The unique ID of the document | **Example Usage** > "Show me the version history for document def456" Returns each version's number, ID, title, author, change log entry, and a content preview. --- ### restore\_document\_version Restore a document to a previous canonical snapshot. Complete and synthetic snapshots restore every canonical field; an exact unchanged restore is a no-op. The operation doesn't overwrite history. **Parameters** | Parameter | Type | Required | Description | | ------------------ | -------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------- | | `documentId` | `string` | Yes | The unique ID of the document | | `versionId` | `string` | Yes | The ID of the version to restore (from `get_document_versions`) | | `expectedRevision` | `number` | Yes | Required current revision from `get_document` or the latest successful document acknowledgement, not the target historical version number | **Example Usage** > "Restore document def456 to version xyz789" Returns the same compact acknowledgement as `update_document`. Restoring a legacy partial snapshot also returns `warnings: ["LEGACY_PARTIAL_SNAPSHOT"]`; fields absent from that historical snapshot are preserved. --- ## Collections ### list\_collections List one page of collections in your workspace with optional name filtering. **Parameters** | Parameter | Type | Required | Description | | --------- | ---------- | -------- | ------------------------------------------------------------- | | `search` | `string` | No | Filter collections by name | | `limit` | `number` | No | Maximum number of collections to return (default: 20) | | `cursor` | `string` | No | Opaque cursor from a previous response to fetch the next page | | `tags` | `string[]` | No | Tag filter (AND-semantics: all supplied tags must match) | **Example Usage** > "List my collections" Returns each collection's name, description, icon, color, item count, and ID, plus pagination metadata. If `hasMore` is true, pass the returned cursor to the next `list_collections` call. --- ### get\_collection Get details of a specific collection, optionally including up to 50 member items. **Parameters** | Parameter | Type | Required | Description | | -------------- | --------- | -------- | -------------------------------------------------------- | | `collectionId` | `string` | Yes | The unique ID of the collection to retrieve | | `includeItems` | `boolean` | No | Whether to include up to 50 member items (default: true) | **Example Usage** > "Show me the 'Frontend Prompts' collection with its member items" Returns the collection's name, description, icon, color, item count, and, if `includeItems` is true, up to 50 prompts and documents in the collection. The tool doesn't expose a member cursor. Use the paginated REST collection-items endpoint when you need every member. --- ### create\_collection Create a new collection to organize your prompts and documents. **Parameters** | Parameter | Type | Required | Description | | ------------- | ---------- | -------- | ----------------------------------------------- | | `name` | `string` | Yes | Name of the collection | | `description` | `string` | No | Description of what the collection contains | | `color` | `string` | No | Color code for the collection (e.g., "#f97316") | | `icon` | `string` | No | Emoji icon for the collection (e.g., "📁") | | `tags` | `string[]` | No | Tags for categorizing the collection | **Example Usage** > "Create a collection called 'Code Review' with a 🔍 icon and blue color #3b82f6" Returns the new collection's ID, icon, and color. --- ### update\_collection Update a collection's metadata. Only provide the fields you want to change. **Parameters** | Parameter | Type | Required | Description | | -------------- | ---------- | -------- | ------------------------------------------ | | `collectionId` | `string` | Yes | The unique ID of the collection to update | | `name` | `string` | No | New name for the collection | | `description` | `string` | No | New description | | `color` | `string` | No | New color code | | `icon` | `string` | No | New emoji icon | | `tags` | `string[]` | No | Replace tags (send `[]` to clear all tags) | **Example Usage** > "Rename the collection ghi789 to 'Code Quality' and change its icon to ✅" Returns a confirmation with the updated collection name. --- ### delete\_collection Delete an empty collection. The collection must be empty, so remove all member items first. Removing an item from the collection does not delete the prompt or document from your workspace. **Parameters** | Parameter | Type | Required | Description | | -------------- | -------- | -------- | ----------------------------------------- | | `collectionId` | `string` | Yes | The unique ID of the collection to delete | **Example Usage** > "Delete collection ghi789" Returns a confirmation after deleting the empty collection. A non-empty collection returns a conflict instead. > **Note:** Remove each member with `remove_from_collection`, then delete the empty > collection. Removing members only severs their collection association; your > prompts and documents remain in your workspace. --- ### add\_to\_collection Add prompts or documents to a collection. You can add multiple items at once. **Parameters** | Parameter | Type | Required | Description | | -------------- | -------------------------- | -------- | -------------------------------------- | | `collectionId` | `string` | Yes | The collection to add items to | | `itemIds` | `string[]` | Yes | Array of document or prompt IDs to add | | `itemType` | `"document"` \| `"prompt"` | Yes | Type of items being added | **Example Usage** > "Add prompts abc123 and abc456 to collection ghi789" Returns the number of items added and how many were already in the collection. --- ### remove\_from\_collection Remove prompts or documents from a collection. The items themselves aren't deleted. **Parameters** | Parameter | Type | Required | Description | | -------------- | -------------------------- | -------- | ----------------------------------------- | | `collectionId` | `string` | Yes | The collection to remove items from | | `itemIds` | `string[]` | Yes | Array of document or prompt IDs to remove | | `itemType` | `"document"` \| `"prompt"` | Yes | Type of items being removed | **Example Usage** > "Remove document def456 from collection ghi789" Returns the number of items removed. --- ## Search ### find\_items Search across prompts, documents, and collections using semantic similarity or keyword matching. This is the primary search tool — it returns item-level results (titles, IDs, relevance scores) across all content types. For deep content exploration within documents, use [Deep Search](https://contextrepo.com/docs/mcp/tools-reference#deep-search) instead. **Parameters** | Parameter | Type | Required | Description | | ---------- | ---------------------------------------------------------- | -------- | ---------------------------------------------------------------------------------------------------------------- | | `query` | `string` | Yes | The search query | | `type` | `"prompts"` \| `"documents"` \| `"collections"` \| `"all"` | No | Filter results by type (default: "all") | | `semantic` | `boolean` | No | Use semantic search for natural language understanding (default: true). Set to false for exact literal matching. | | `tags` | `string[]` | No | Tag filter (AND-semantics: all supplied tags must match) | **Example Usage** > "Find everything related to machine learning in my workspace" Returns results grouped by type (prompts, documents, collections) with relevance scores for semantic search. **Structured output** `structuredContent` has this top-level shape: ```ts { data: { prompts: Array<{ promptId: string title: string description: string tags: string[] score?: number highlight?: string }> documents: Array<{ documentId: string title: string tags: string[] score?: number highlight?: string chunkId?: string }> collections: Array<{ collectionId: string name: string tags: string[] description?: string score?: number matchedItems?: number }> } meta: { query: string semantic: boolean latencyMs?: number } } ``` The identifier field depends on the result type: `promptId`, `documentId`, or `collectionId`. `find_items` does not return a generic `id` field. Semantic results include scores; literal results may include a matching `highlight`, and document body matches may also include a `chunkId`. `find_items` returns item-level metadata and optional snippets, not full stored content. Use `read_prompt` for full prompt content or `get_document` for document content up to the REST response limit. Use `search` followed by `fetch` when you need the ChatGPT Company Knowledge contract. > **Semantic vs. keyword search:** Semantic mode (the default) finds conceptually related content — searching for "ML training" will match documents about "machine learning models." Keyword mode does exact literal matching on titles, descriptions, and indexed document body text via hierarchical chunks — full-body literal matching, eventually consistent with chunking. Title and preview matches are immediate. --- ## ChatGPT App compatibility The `search` and `fetch` tools implement the OpenAI Apps SDK Company Knowledge contract used by the ChatGPT App. ### search Search your prompts, documents, and collections and return a flat list of citation-ready results. **Parameters** | Parameter | Type | Required | Description | | --------- | -------- | -------- | ---------------- | | `query` | `string` | Yes | The search query | Each result contains an opaque `id`, a `title`, and a dashboard `url`. Pass the opaque `id` to `fetch`. Prompt IDs return full stored content; document IDs return content up to the REST response limit; collection IDs return metadata plus up to 50 member items. --- ### fetch Fetch full prompt content, document content up to the REST response limit, or collection metadata plus up to 50 member items, with a citation URL. Use `deep_search` for targeted retrieval from large documents. **Parameters** | Parameter | Type | Required | Description | | --------- | -------- | -------- | ------------------------------------------------------------------ | | `id` | `string` | Yes | The opaque prompt, document, or collection id returned by `search` | The response contains `id`, `title`, Markdown `text`, `url`, and type metadata. --- ## Deep Search Deep Search is a set of 3 tools for progressively exploring document content. Unlike `find_items` (which returns item-level catalog results), Deep Search returns granular content fragments with structural hierarchy — sections, paragraphs, and navigation links. The typical workflow: start with `deep_search` to find relevant passages, use `deep_read` to examine a chunk in detail, and `deep_expand` to navigate through the document's structure. ### deep\_search Search within document content using vector similarity and get ranked, hierarchical chunks with navigation links. **Parameters** | Parameter | Type | Required | Description | | -------------- | -------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `query` | `string` | Yes | The search query for vector similarity matching | | `limit` | `number` | No | Maximum number of results to return (default: 10) | | `sessionId` | `string` | No | Omitting `sessionId` creates or reuses the caller's auto-session and is the normal MCP workflow. An explicit `sessionId` must have been minted by `POST /v1/pd/session` for the same caller; arbitrary values are rejected. | | `collectionId` | `string` | No | Filter results to a specific collection | | `documentId` | `string` | No | Filter results to a specific document | **Example Usage** > "Deep search my documents for information about authentication best practices" Returns ranked chunks, each with a `chunkId`, hierarchy level (document/section/paragraph), content preview, and navigation links (parent, siblings). Use the `chunkId` with `deep_read` or `deep_expand` to explore further. --- ### deep\_read Read a single document chunk with full content and hierarchy metadata. Use this after `deep_search` to inspect a result in detail, or after `deep_expand` to examine a navigated chunk. **Parameters** | Parameter | Type | Required | Description | | --------- | -------- | -------- | ------------------------------------------------------------------ | | `chunkId` | `string` | Yes | The chunk ID to read (from `deep_search` or `deep_expand` results) | **Example Usage** > "Read chunk abc123 in full" Returns the chunk's complete text, structural position (section path, chunk index), navigation IDs (parent, previous sibling, next sibling), and content metadata (word count, heading text). --- ### deep\_expand Navigate the document hierarchy from a chunk in 5 directions. Use this after `deep_search` to explore related content without re-searching. **Parameters** | Parameter | Type | Required | Description | | ----------- | ----------------------------------------------------------------- | -------- | ------------------------------------------------------------------------- | | `chunkId` | `string` | Yes | The chunk ID to expand from (from `deep_search` or `deep_expand` results) | | `direction` | `"up"` \| `"down"` \| `"next"` \| `"previous"` \| `"surrounding"` | Yes | Navigation direction | | `count` | `number` | No | Number of chunks to return | **Directions** | Direction | What it returns | | ------------- | ------------------------------------------------------------- | | `up` | The parent chunk (one level higher in the document hierarchy) | | `down` | Child chunks (one level deeper) | | `next` | The next sibling chunk at the same level | | `previous` | The previous sibling chunk at the same level | | `surrounding` | A context window of nearby siblings | **Example Usage** > "Expand chunk abc123 downward to see its sub-sections" Returns the chunks in the requested direction, each with its own `chunkId` for further navigation. --- ## Reasoning Reasoning is a single tool that sits one layer above Deep Search. Where `deep_search` returns ranked chunks for you to read, `reason` performs bounded retrieval and returns a best-effort cited answer projected from strict cited `statements` and `limitations`, with the exact chunks it cited and best-effort gaps. The `gaps` list is non-exhaustive. See [Reasoning](https://contextrepo.com/docs/concepts/reasoning) for a task-oriented guide. ### reason Ask a question and get a synthesized, cited answer composed across your documents — not a list of chunks. Read-only. **Parameters** | Parameter | Type | Required | Description | | -------------- | -------- | -------- | -------------------------------------------------------------------------------------------------------------------- | | `query` | `string` | Yes | The natural-language question to answer across your documents; it must contain at least one non-whitespace character | | `limit` | `number` | No | Maximum number of evidence chunks in the synthesis packet. Defaults to 50 and is clamped to 1–50. | | `documentId` | `string` | No | Restrict reasoning to a single document | | `collectionId` | `string` | No | Restrict reasoning to a single collection | The MCP tool doesn't expose `maxTokens`; the server uses the default 8000-token evidence budget. Use the REST endpoint when you need to set that budget. **Response** | Field | Type | Description | | ----------- | ---------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `answer` | `string` | The synthesized prose answer composed across the gathered evidence | | `citations` | `array` | Each citation includes `chunkId`, `documentId`, and `documentTitle` for the chunks the answer cites | | `gaps` | `string[]` | Best-effort limitations noticed in this run, including facts not established by the retrieved evidence within the requested scope and retrieval limits | | `meta` | `object` | `chunksGathered`, `citationsDropped`, and `latencyMs`. `citationsDropped` counts references withheld by failed mechanical validation; retained duplicate references do not increase it. This diagnostic is not a semantic-correctness score. | The readable MCP `content` always includes **Answer** and **Meta**, then adds **Sources** and **Limitations** when those arrays aren't empty. `structuredContent` preserves the REST response object. Exact citation validation proves source linkage, not semantic entailment. Gaps remain bounded to best-effort limitations noticed during this run, including facts not established by the retrieved evidence within the requested scope and retrieval limits. They are non-exhaustive and do not prove repository-wide absence. The tool uses at most one synthesis call with zero retries through a server-managed model. Empty evidence always skips synthesis. Weak unscoped evidence also skips synthesis. Nonempty explicit document or collection scope bypasses only Reason's fixed relevance gate. It operates on document content only and does not persist the answer or a reasoning trace. The strict provider result contains `statements` and `limitations`. Disagreements appear as ordinary cited statements in the answer. **Example Usage** > "Using my documents, what is our refund policy for annual plans?" Returns a cited answer that draws only on your stored content, with each claim traceable to a specific chunk via the `citations` array. --- ## Related Pages - [MCP Overview](https://contextrepo.com/docs/mcp): What MCP is, why it matters, and authentication methods. - [Cursor Setup](https://contextrepo.com/docs/mcp/setup-guides/cursor): Connect Context Repo to Cursor with one click. - [Claude Desktop Setup](https://contextrepo.com/docs/mcp/setup-guides/claude-desktop): Configure the MCP Server in Claude Desktop. - [Other Clients](https://contextrepo.com/docs/mcp/setup-guides/other-clients): Generic setup for compatible clients via stdio or Streamable HTTP.