> ## Documentation index
> Fetch the complete documentation index at: https://contextrepo.com/docs/llms.txt
> Use it to find every page before exploring further.

# MCP Server

> Connect your AI assistant to Context Repo with the Model Context Protocol (MCP) to manage prompts, documents, collections, and search from Claude, Cursor, VS Code, and more.

The Model Context Protocol (MCP) is an open standard that lets AI assistants connect to external tools and data sources. Instead of copying and pasting between your AI assistant and Context Repo, MCP gives your assistant direct access to your prompts, documents, and collections — so it can read, create, update, and search your workspace without you ever leaving the conversation.

## Why MCP Matters

Without MCP, working with AI context looks something like this:

- Open Context Repo in one tab, your AI assistant in another
- Copy a prompt, switch tabs, paste it in
- Get a response, switch back, save it as a document
- Repeat for every interaction

With the Context Repo MCP Server, your AI assistant handles all of this directly. Ask it to list your prompts, create a document, search your collections, or explore content chunk by chunk — all through natural conversation.

One connection. The current hosted tool set. Zero tab-switching.

## Tools Overview

The hosted MCP Server defines the tools available to every connection,
including the `search` and `fetch` aliases used by ChatGPT. The
`context-repo-mcp` v3 command is a stdio bridge to that same hosted endpoint,
so its tool schemas and behavior update with the hosted server rather than a
separate package implementation.

### User Info

| Tool            | Description                                           |
| --------------- | ----------------------------------------------------- |
| `get_user_info` | Get your account details (name, email, profile image) |

### Prompts (7 tools)

| Tool                     | Description                                                                       |
| ------------------------ | --------------------------------------------------------------------------------- |
| `search_prompts`         | List one prompt page; optional search filters that page by title or description   |
| `read_prompt`            | Get a specific prompt's full content, variables, and metadata                     |
| `create_prompt`          | Create a new prompt template with title, description, and content                 |
| `update_prompt`          | Update an existing prompt's title, description, or content                        |
| `delete_prompt`          | Permanently delete a prompt                                                       |
| `get_prompt_versions`    | List recorded versions with change logs and content previews up to 200 characters |
| `restore_prompt_version` | Restore a prompt to a previous version                                            |

### Documents (7 tools)

| Tool                       | Description                                                                                                                  |
| -------------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
| `list_documents`           | List one page of documents with optional title filtering                                                                     |
| `get_document`             | Get document content up to the REST response limit and metadata; use Deep Search for targeted retrieval from large documents |
| `create_document`          | Create a new text document with optional tags                                                                                |
| `update_document`          | Update canonical document fields with required `expectedRevision` and no-op detection                                        |
| `delete_document`          | Permanently delete a document                                                                                                |
| `get_document_versions`    | View a document's version history with change logs                                                                           |
| `restore_document_version` | Restore a document with required `expectedRevision`                                                                          |

### Collections (7 tools)

| Tool                     | Description                                                     |
| ------------------------ | --------------------------------------------------------------- |
| `list_collections`       | List one page of collections with optional name filtering       |
| `get_collection`         | Get collection details and, by default, up to 50 member items   |
| `create_collection`      | Create a new collection with name, description, icon, and color |
| `update_collection`      | Update a collection's name, description, icon, or color         |
| `delete_collection`      | Delete an empty collection; remove all member items first       |
| `add_to_collection`      | Add prompts or documents to a collection                        |
| `remove_from_collection` | Remove prompts or documents from a collection                   |

### Search (1 tool)

| Tool         | Description                                                                                                                                      |
| ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| `find_items` | Search across prompts, documents, and collections using semantic similarity or keyword matching. Filter by type and toggle between search modes. |

### ChatGPT App compatibility (2 tools)

| Tool     | Description                                                                                                                                                                                               |
| -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `search` | Return citation-ready results through the OpenAI Apps SDK Company Knowledge contract                                                                                                                      |
| `fetch`  | Fetch full prompt content, document content up to the REST response limit, or collection metadata plus up to 50 members, with a citation URL; use Deep Search for targeted retrieval from large documents |

### Deep Search (3 tools)

| Tool          | Description                                                                                         |
| ------------- | --------------------------------------------------------------------------------------------------- |
| `deep_search` | Search within document content and get ranked, hierarchical chunks with navigation links            |
| `deep_read`   | Read a specific chunk with full content, structural position, and metadata                          |
| `deep_expand` | Navigate from a chunk in 5 directions: up (parent), down (children), next, previous, or surrounding |

Deep Search is designed for exploring large documents progressively. Start with `deep_search` to find relevant passages, use `deep_read` to examine them in detail, and `deep_expand` to navigate through the document's structure without loading everything at once.

> **Note:** The required MCP revision parameter described here comes from the hosted
> `https://contextrepo.com/mcp` endpoint and passes through the
> `context-repo-mcp` v3 stdio bridge unchanged. Raw REST lease credentials are
> not MCP tool inputs.

### Reasoning (1 tool)

| Tool     | Description                                                                                                        |
| -------- | ------------------------------------------------------------------------------------------------------------------ |
| `reason` | Ask a question and get a best-effort cited answer with inline citations and non-exhaustive limitations (read-only) |

Reasoning sits one layer above Deep Search: instead of returning ranked chunks for you to read, `reason` gathers the most relevant evidence and composes a single cited answer. Use it when you want an answer, not a result list.

`reason` is read-only and works on document content, not prompts. The server
keeps citation provenance and best-effort limitations explicit. Disagreements
appear as ordinary cited statements in the answer. An empty `gaps` array does
not prove complete coverage. See the
[Reasoning guide](https://contextrepo.com/docs/concepts/reasoning) for examples and response details.

## Safe Document Updates

`get_document` returns the canonical document revision, content hash, change
time, and canonical application ETag. MCP `update_document` and
`restore_document_version` both
require `expectedRevision`, a nonnegative safe integer from `get_document` or
the latest successful document acknowledgement. For restore, pass 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. The backend compares that revision atomically with
the current document. A stale value returns `REVISION_MISMATCH`.

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.

Changed writes return a compact acknowledgement with the document ID,
revision, content hash, change time, and `noop` status. Exact unchanged updates
return `noop: true`. Restoring an incomplete historical snapshot can also
return `LEGACY_PARTIAL_SNAPSHOT`.

Documents using `lease_required` managed editing must use the REST coordination
workflow. MCP does not accept lease credentials.

## Authentication

The MCP Server supports two authentication methods, depending on the client and connection path:

- **OAuth** — Remote MCP clients that implement the authorization flow can connect to `https://contextrepo.com/mcp` and sign in with Context Repo. Interactive OAuth tokens carry the signed-in user's authority.
- **API key** — Generate a key from **Dashboard > Settings > API Keys** and grant only the prompt or document scopes the installation needs. The documented Cursor and Claude Desktop stdio configurations use the `context-repo-mcp` v3 bridge with this key.

Both methods resolve to the same Context Repo account, but API-key calls remain
limited by the key's scopes. The stdio npm package forwards to the hosted
endpoint and does not maintain a separate inventory.

> **Note:** Grok uses the dedicated `https://contextrepo.com/grok-mcp` compatibility endpoint so its first request receives an OAuth challenge. It exposes the same 29 hosted tools as `/mcp`. Follow the [Grok integration guide](https://contextrepo.com/docs/integrations/grok) instead of the generic client setup.

## Get Started

Ready to connect your AI assistant?

- [Cursor](https://contextrepo.com/docs/mcp/setup-guides/cursor): One-click setup with automatic configuration.
- [Claude Desktop](https://contextrepo.com/docs/mcp/setup-guides/claude-desktop): JSON config for macOS and Windows.
- [VS Code](https://contextrepo.com/docs/mcp/setup-guides/vs-code): Connect through VS Code's MCP support.
- [Grok](https://contextrepo.com/docs/integrations/grok): Add Context Repo as a custom connector with hosted OAuth sign-in.
- [Grok Bot](https://contextrepo.com/docs/integrations/grok-bot): Add Context Repo as a Grok Bot plugin with hosted OAuth sign-in.
- [Windsurf](https://contextrepo.com/docs/mcp/setup-guides/windsurf): Set up Context Repo in Windsurf.
- [Other Clients](https://contextrepo.com/docs/mcp/setup-guides/other-clients): Generic setup for compatible clients via stdio or Streamable HTTP.
- [Tools Reference](https://contextrepo.com/docs/mcp/tools-reference): Full parameter details for the current hosted tools.