Click on "Install Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@mcp-retrieve search for 'token-level relevance' in my docs"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
An MCP server that exposes late-interaction
document retrieval (ColBERT-style MaxSim) over a local folder. Point it at a
directory of text/markdown/code, and any MCP client — Claude Desktop, an IDE
agent, your own host — can index it and search it with token-level
relevance.
It ships with a deterministic, model-free default embedder, so the server and its full test suite run offline with no model weights, no API key, no network. When you want production-grade semantics, drop in a real ColBERT / ColQwen encoder behind a small protocol — ranking code does not change.
The Model Context Protocol is an open standard that lets LLM applications
connect to external tools and data through a uniform server interface. A host
(e.g. Claude Desktop) launches MCP servers and calls the tools they
advertise. mcp-retrieve is such a server; it advertises two tools:
Tool | Purpose |
| Read text files under |
| Rank indexed chunks by MaxSim late interaction and return the top |
Related MCP server: ragi
Most dense retrievers compress a passage into one vector and compare it to one query vector — cheap, but lossy. Late interaction, introduced by ColBERT (Khattab & Zaharia, ColBERT: Efficient and Effective Passage Search via Contextualized Late Interaction over BERT, SIGIR 2020, arXiv:2004.12832), keeps one vector per token for both the query and the document and defers their interaction to scoring time via the MaxSim operator:
score(q, d) = Σ_i max_j sim(q_i, d_j)Each query token q_i is matched to its single most similar document token
d_j, and those per-token maxima are summed. This preserves fine-grained term
matching (a query term can find its evidence anywhere in the passage) while
staying efficient. With L2-normalised vectors, sim is cosine similarity, so
MaxSim reduces to a dot product followed by a row-wise max and a sum — which is
exactly what mcp_retrieve.retrieval.maxsim computes.
pip install -e . # core: mcp + numpy
pip install -e ".[dev]" # plus pytest for the test suiteFor Claude Desktop, add the server to its mcpServers config
(claude_desktop_config.json):
{
"mcpServers": {
"mcp-retrieve": {
"command": "mcp-retrieve"
}
}
}If you installed into a virtual environment, use the absolute path to the
mcp-retrieve console script (or "command": "python", "args": ["-m", "mcp_retrieve"]). Restart the client, then ask it to index a folder and search
it — the model will call the index_folder and search tools.
from mcp_retrieve import RetrievalIndex
index = RetrievalIndex() # deterministic default embedder
index.index_folder("./docs")
for hit in index.search("late interaction maxsim", k=5):
print(f"{hit.score:.3f} {hit.chunk.source} {hit.snippet}")The default HashingEmbedder makes the project run anywhere, but it matches on
character n-grams, not meaning. For real semantics, implement the Embedder
protocol around a trained encoder and pass it in:
import numpy as np
from mcp_retrieve import RetrievalIndex
from mcp_retrieve.server import create_server
class ColbertEmbedder:
"""Wrap a ColBERT checkpoint as a multi-vector Embedder."""
def __init__(self, checkpoint: str) -> None:
from colbert.modeling.checkpoint import Checkpoint
from colbert.infra import ColBERTConfig
self._ckpt = Checkpoint(checkpoint, ColBERTConfig())
@property
def dim(self) -> int:
return 128
def embed(self, text: str) -> "np.ndarray":
vecs = self._ckpt.docFromText([text])[0] # (num_tokens, 128)
return np.asarray(vecs, dtype=np.float32)
# Use it from Python …
index = RetrievalIndex(embedder=ColbertEmbedder("colbert-ir/colbertv2.0"))
# … or run the MCP server with it.
server = create_server(embedder=ColbertEmbedder("colbert-ir/colbertv2.0"))
server.run()Any object exposing dim: int and embed(text) -> ndarray[num_tokens, dim]
with L2-normalised rows satisfies the protocol — ColBERT, ColQwen, ColPali, or
your own. The ranking and chunking code is encoder-agnostic.
src/mcp_retrieve/
embedder.py # Embedder protocol + deterministic HashingEmbedder default
retrieval.py # chunking, MaxSim, RetrievalIndex (pure — no MCP dependency)
server.py # FastMCP server exposing index_folder + search (only MCP import)The retrieval and embedding cores import nothing MCP-related, so they are
testable and reusable on their own; the SDK is isolated to server.py and
imported lazily.
python -m pytestAll retrieval and embedder tests run offline with the default embedder. The
end-to-end FastMCP tool test is skipped automatically when the mcp package is
not installed.
MIT © 2026 Max Baluev
Index all text files under a local folder for retrieval.
Reads supported text files recursively, splits them into overlapping chunks, and embeds each chunk into a multi-vector representation. Re-indexing replaces any previous index. Returns the number of files and chunks indexed.
Args: folder: Path to a local directory to index.
| Name | Required | Description | Default |
|---|---|---|---|
| folder | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description fully discloses behavior: recursive reading, splitting, embedding, re-indexing replacement, and return values. Minor gap: no mention of whether the tool requires write permissions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise paragraphs with an args list, front-loaded purpose, no fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given a simple single-param tool with output schema, the description covers all necessary behavioral and return value aspects.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The 'Args' section clarifies the 'folder' parameter as a path to a local directory, adding meaning beyond the schema's bare type. Could specify path format but sufficient for a single required param.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool indexes all text files under a local folder for retrieval, with a specific verb and resource. It distinguishes from the sibling 'search' by implying this is the indexing step.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implicitly suggests using this before search, but does not explicitly state when to use vs alternatives, nor any exclusions or prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search the indexed folder with ColBERT-style MaxSim late interaction.
Embeds the query into token vectors and ranks every indexed chunk by
score(q, d) = sum_i max_j sim(q_i, d_j). Returns up to k results,
highest score first, each with its source file, score, and a snippet.
Args: query: Natural-language or keyword query. k: Maximum number of results to return (default 5).
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | ||
| k | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses scoring formula, result count limit, and returned fields (source file, score, snippet). Lacks discussion on side effects or performance, but no annotations provided.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Concise with structured args section, though the detailed formula may be more than needed for typical usage.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers key aspects: search action, algorithm, parameters, and return format. Lacks pagination details but adequate for basic use given output schema existence.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema coverage, description fully explains query (natural-language or keyword) and k (max results, default 5), adding necessary meaning.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states search action on indexed folder, specifies retrieval method (ColBERT MaxSim), and output format. Distinguishes from sibling index_folder.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Implied usage for querying vs. indexing but no explicit when-to-use or alternatives compared to index_folder.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.
v0.1.0index_foldersearchThe two tools have entirely non-overlapping purposes: one indexes a folder, the other performs searches. There is no ambiguity between them.
Both tool names follow a clear verb_noun pattern (index_folder, search). The second tool uses a single verb, which is consistent and concise for its action.
With only two tools, the server is minimal but well-scoped for its purpose (index and retrieve). It covers the essential operations without unnecessary extras.
The pair index+search provides a complete core workflow for retrieval. Missing operations like listing indexed files or deleting specific entries are minor gaps that do not break the main use case.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
MCP server for searching Airweave collections with natural language queries.
Token-free MCP server for structured RevoGrid Core, Pro, and Enterprise knowledge retrieval.
MCP server for querying Forkast documentation
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/maxbaluev/mcp-retrieve'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
