Local directory
A folder mounted into the container, scanned in place. Nothing is copied, and it is mounted read-only.
handbook/install.mdSelf-hosted · MCP · AGPL-3.0
Give your agent
your documentation.
Not your data.
Contextator merges a mounted folder, a git repository, an upload, a Notion workspace, a Confluence site and a published documentation site into one semantically searchable MCP endpoint per project — running in a single Docker container on your own machine.
No vendor account · No API key · No egress by default
~
docker run -d --name contextator -p 127.0.0.1:3444:3444 \
-v contextator-pgdata:/var/lib/postgresql/data \
-v contextator-models:/app/.cache/models \
-v contextator-data:/data \
-v /path/to/your/docs:/docs:ro \
contextator/contextator
postgres 16 + pgvector ready
embedding model ready — 384-d, local CPU
listening on :3444
→ setup code in: docker logs contextator
search_docs("which file types can it index")
wiki/FAQ.mdFAQ > Which file types are indexed?
0.908wiki/Document-Sources.mdDocument Sources > What gets indexed
0.880If the best hit is below SEARCH_SCORE_FLOOR (0.82), it answers “no good match” instead of guessing.
Works withClaude CodeCursorClaude Desktopany MCP client
Streamable HTTP + legacy SSE on one URLThe problem
Documentation is multi‑homed. Your agent is not.
A product's knowledge is genuinely spread across a repository, a wiki, a vault and an export. Every existing answer asks a human to consolidate first — which never happens.
- 01
Paste it into the prompt
Bounded by the context window, stale the moment it is pasted, and repeated by every developer on the team.
- 02
Let the agent grep the repo
Fine for docs in the same checkout. Useless for the handbook in Notion, the API reference in another repository, the vault on an architect's laptop.
- 03
Use a hosted RAG service
Solves retrieval by shipping internal documentation to a third party, one account per team, billed per query. For many organisations that ends the conversation.
- 04
Build a one-off MCP server
Every team writes the same chunker, the same embedding loop, the same incremental indexer — and then maintains it.
Three named alternatives, compared honestly.
Contextator next to Context7, a hosted RAG service (Pinecone Assistant) and a local documentation MCP server (Grounded Docs). Rows marked “Contextator is weaker here” are where at least one of them does better. Every cell about another product restates its own public documentation; where that says nothing, so does the cell.
| Compared on | Contextator | Context7 | Pinecone Assistant | Grounded Docs MCP Server |
|---|---|---|---|---|
| Where it runs | On your server — one Docker container you run. | Context7’s cloud. Self-hosting the whole stack is an Enterprise option with a licence key. | Pinecone’s managed service. | On your machine, through npx or Docker. |
| Setup before the first answerContextator is weaker here | Run the container, create the first account with the one-time setup code from its log, create a project, add a source, wait for its first index, then point your client at the project’s MCP URL. | Add its remote MCP URL to your client. A free API key raises the rate limits. | Create an assistant, upload files, then connect its MCP endpoint with a Pinecone API key. | Start it, then add each documentation source via its CLI, an MCP tool or its web interface. |
| Ready-made public library docsContextator is weaker here | None — it indexes only the sources you add. | Yes — a shared catalogue of public libraries, refreshed automatically. | None — it answers from the files you upload. | No catalogue — it fetches the websites, repositories and npm or PyPI packages you name. |
| Your internal sources | Local folder, git (private repositories with a token), upload, Notion, Confluence and a public documentation site. | Private GitHub, GitLab, Bitbucket and other git repositories, Confluence and OpenAPI specs — on Pro or Enterprise. | Files you upload. | Local folders, zip archives, websites and GitHub repositories. |
| File formatsContextator is weaker here | Markdown, MDX, HTML, PDF, Word, CSV and plain text, inside archives too; OpenAPI, Obsidian and Notion exports get their own handling. | Markdown, MDX, reStructuredText, plain text and Jupyter notebooks; examples are generated from source code only when a repository has little documentation. | PDF, Word, Markdown, plain text and JSON. | Wider — PDF, Word, Markdown and MDX, plus Excel, PowerPoint, OpenDocument, EPUB, Jupyter notebooks and source code. |
| Where your documents go | They stay on your server, except text sent to OpenAI if you switch embeddings to it. | Hosted: to Context7’s service. Self-hosted: only the content needed for parsing, embedding, reranking or generating docs from source code, to the AI provider you choose. | Uploaded to Pinecone, which chunks, embeds and stores them. | They stay on your machine, except text sent to an embedding provider you configure — OpenAI by default when its key is set. |
| Operated for youContextator is weaker here | No — upgrades, backups and uptime are yours. | Yes, on the hosted service. | Yes. | No — it runs on your machine. |
| Licence | AGPL-3.0-or-later, or a commercial licence. | MCP server under MIT; its API backend, parser and crawler are private. | A managed service on Pinecone’s terms; its local MCP server is open source. | MIT. |
Sources: Context7, Pinecone Assistant, Grounded Docs MCP Server. Their docs were read on 25 September 2026.
How it works
Six kinds of source in. One URL out.
An index run syncs every source, walks the result, chunks each file along its headings and embeds the chunks next to their document. Your question travels the same path in reverse — as meaning and as exact wording at once.
Sources
local directorygit repositoryupload / archivenotion workspaceconfluencedocumentation site
Index run
sync · scan · sha256chunk at headings, keep the breadcrumbembed on CPU, in batches
unchanged → skippedStorage
PostgreSQL 16 + pgvector, inside the containerHNSW vector index and a tsvector GIN, side by side127.0.0.1, not published
Endpoint/mcp/billing
search_docslist_topicsread_document
Incremental. Files are hashed. Re-indexing an unchanged collection performs zero embeddings.
Isolated. Every query is scoped by project; a session issued for one is rejected on another.
Observable. Every run is persisted with its mode, counts, duration and error.
Sources
Point it at where the docs already are.
A project may hold any number of sources at once. Each one syncs on its own and fails on its own — a broken source never empties the index.
Git repository
A shallow single-branch checkout over HTTPS. Private repos with a token, one subdirectory if you like, re-indexed by push webhook.
api-repo/reference/auth.mdUploads & archives
Drop files, whole folders or a .zip, .tar or .rar on the dashboard. Extracted with traversal and decompression-bomb guards.
spec-2024/overview.mdObsidian vault
A content-type transform on an upload, folder or repo, not a source of its own: wikilinks in all their forms, callouts and %%comments%% flattened to ordinary Markdown before a single chunk is cut.
vault/architecture.mdNotion workspace
Every page shared with your integration, rendered to Markdown and kept in sync by last_edited_time.
notion/onboarding.mdConfluence
Every page in the spaces you name, rendered to Markdown and nested the way it is in the wiki. Confluence Cloud or Data Center 7.9 and later — not Confluence Server.
wiki/eng/runbooks.mdDocumentation site
A published site, found through its sitemap, its llms.txt or a crawl from one start URL. Public pages only, converted by the same transform uploaded HTML goes through, and re-fetched with conditional GETs.
vendor-docs/guide/install.mdEvery path says where it came from
A source's name is the first segment of every document it contributes. That is what tells the agent which repository an answer came from — and what lets two sources hold the same file name.
The MCP surface
Three tools. Read-only, on purpose.
The agent gets a tiny, self-describing surface — so you ask a question instead of naming a tool. Complexity lives in the dashboard, where a human is looking.
search_docs(query, limit, source, path_prefix, version)Hybrid search across the project's chunks — meaning and exact wording fused by rank, so an environment variable finds its page as readily as a question does. Ranked excerpts, each with its file path, heading breadcrumb and score; source, path_prefix and version narrow it to one source, one directory or one release.
- read-only
- idempotent
- limit 1–20
list_topics(cursor, limit)Everything the project holds, grouped by directory, with titles, chunk counts and the source each document came from. What an agent calls when it wants to know what exists before it searches — and it pages, so a project of a thousand documents can be listed to the end.
- read-only
- closed-world
read_document(path, heading, from, to, max_tokens)One indexed file, served from the database rather than the disk — so it still reads after the file moved. Pass a heading breadcrumb straight out of a search result to read only that section, or from/to for a chunk range. Only paths indexed for that project are served, never an arbitrary filesystem path, and the answer is capped at max_tokens and says where it cut.
- read-only
- path-contained
An agent cannot write, cannot reach another project, cannot read a file that was not indexed, and cannot trigger an index run. Indexing stays an operator action — dashboard, API or webhook.
The dashboard
The same search your agent runs, where you can see it.
The dashboard sends the query an agent would send to search_docs and shows what comes back: the file, the heading, which half of retrieval found each excerpt, and the raw score. When nothing clears the floor, it says so.
Open the full-size screenshot
Open the full-size screenshotCaptured from a local install of Contextator’s main branch, indexing the project’s own wiki: 28 documents, 1,319 chunks, embedded locally with multilingual-e5-small. Cropped, not edited — every path, rank and score is what that install returned.
Why self-hosted
A useful deployment needs no API key and no outbound connection.
Local by default
Embeddings are computed on your CPU with a 384-dimension multilingual model. Once the model is cached, a default installation makes no outbound call at all.
Hybrid search that can say no
Meaning and exact wording are searched at once and fused by rank, so HALYARD_DISPATCH_TIMEOUT finds its page as readily as a question does. Below the relevance floor — a cosine similarity, 0.82 by default — it answers “no good match” rather than handing over a hit an agent would cite.
Isolated by project
Separate documents, separate embeddings, separate sessions. A client connected to /mcp/billing can never observe /mcp/mobile.
Incremental indexing
Every file carries the sha256 of its raw bytes. A re-index touches only what changed, so a push webhook on every merge stays cheap.
Multilingual retrieval
100 languages including Turkish, on a 384-dimension model that runs on your CPU. Ask in the language the answer is written in: matching across languages is a measured limit of the model, not a switch.
A specification becomes its endpoints
An OpenAPI or Swagger file is indexed as one document per operation — path, method, parameters, schemas, examples — so a search returns GET /pets/{petId} rather than the file that contains three hundred of them. Two releases in one project stay apart: version: "v3" picks one.
One container
PostgreSQL 16 with pgvector ships inside the image, listening only on loopback. No database to install, and no migration command to run — ever.
Old and new clients
Streamable HTTP and the legacy HTTP+SSE transport are served on the same address. The client picks whichever it speaks; you configure nothing.
- 3
- MCP tools
- 6
- Source types
- 384
- Vector dimensions
- 100
- Languages
- 1
- Container to run
- 0
- Bytes of egress
Quick start
From nothing to an answered question in about ten minutes.
Docker with Compose and a folder of Markdown. That is all — the database ships inside the container, and the only slow step happens once.
- 01Start the container.
- 02Create a project and point it at your docs.
- 03Copy the connection snippet the dashboard prints.
- 04Ask your agent a question your documentation answers.
On the serverbash
mkdir contextator && cd contextator
curl -fsSLO \
https://raw.githubusercontent.com/Contextator/Contextator/main/docker-compose.yml
curl -fsSLO \
https://raw.githubusercontent.com/Contextator/Contextator/main/.env.example
cp .env.example .env
docker compose up -d
→ dashboard on http://localhost:3444/
In your projectclaude code
claude mcp add --transport http demo-docs \
http://localhost:3444/mcp/demo
demo-docs connected — 3 tools
Cursor and Claude Desktop snippets are printed by the dashboard, already filled in.
Where the edges are
Honest about what it does not do.
Contextator is built for one deployment shape: your own network, your own operator. The documentation says so in plain words, and so does this page.
What is protected: accounts with root, admin and member roles; source tokens encrypted with AES-256-GCM and never readable again; per-source webhook secrets verified against the raw body before anything is queued; path containment on every read.
A new project is closed from the first second
Creating a project mints its first MCP token and shows the secret once — the endpoint requires it by default. It can be opened per project instead, or switched to require an account, where the project's own memberships reach the endpoint through OAuth 2.1 and are checked on every request.
Text, not pictures of text
Markdown, MDX and plain text are indexed as they are; HTML, Word, CSV and PDF are converted to Markdown at the edge. There is no OCR, so a scanned PDF, an encrypted one, or a Word file that is all images is refused by name rather than half-indexed.
Ask in the language the page is written in
Retrieval covers 100 languages but does not cross between them. Of thirty questions written to cross the boundary, four are answered in the top five — a property of the embedding model, measured in the repository and not presented here as anything else.
No cross-project search
Projects are isolated end to end, deliberately. Two bodies of knowledge that belong to the same question become two sources of one project instead.
Prompt injection is not filtered
Contextator returns your documents faithfully; it does not sanitise intent. Treat the corpus you index as trusted input, because that is what it becomes.
Licensing
Free software. Commercially licensable.
Contextator cannot be closed. Every running instance serves the complete licence text at /license.txt.
GNU AGPL v3 or later
Run it, study it, change it, share it. Using it inside your company asks nothing of you. Let other people reach your modified version over a network, and you owe those users its source.
Read the source on GitHubA separate licence
For organisations whose policy forbids AGPL software, or who need to ship Contextator inside something closed. Granted by the copyright holder.
Ask at tunedness.comFAQ
Short, self-contained answers.
The six questions worth answering before the first docker compose up.
What is Contextator?
A self-hosted MCP server that turns your documentation — a folder, a git repository, an upload, a Notion workspace, a Confluence site or a published documentation site — into one searchable endpoint per project, running in your own Docker container.
Does it send my documentation anywhere?
No. Embeddings are computed on your CPU by default, and the database runs inside the same container. With no remote sources configured, the only outbound traffic is the one-time model download.
Do I need an API key or an account?
No vendor account and no API key — but a project's MCP endpoint is closed as it ships. Creating a project mints its first bearer token and shows it once, and the client sends it with every request; the port itself is published on 127.0.0.1 only. Each project's endpoint has three settings: token, the default; an account of this instance signing in over OAuth 2.1; or open, which you choose deliberately. The dashboard is different again: it creates one local account on first run, behind a one-time setup code printed in the container logs, so it stays your own instance with no vendor involved.
Which MCP clients work with it?
Any client that speaks MCP. Claude Code, Cursor and Claude Desktop are the ones this site walks through, all connecting to the same URL over Streamable HTTP or the legacy HTTP+SSE transport.
What can it index?
Six kinds of source — a local folder, a git repository, an upload, a Notion workspace, a Confluence site and a public documentation site read from its sitemap — merged into one project. Markdown, MDX and plain text are indexed as they are, and HTML, Word, CSV and PDF files are converted to Markdown as they are indexed; an OpenAPI or Swagger specification becomes one document per operation. There is no OCR, so a scanned PDF or an image is out of scope and is reported rather than indexed.
Is it free? Can I use it commercially?
Yes to both. Contextator ships under AGPL-3.0-or-later, so running the unmodified software — even inside a company — costs nothing and asks nothing of you; the licence only asks for source in return once you let others reach a modified version over a network. A separate commercial licence is available for anyone whose policy forbids AGPL or who needs to embed it in something closed.
Your documentation is already written. Let the agent read it.
One docker compose up -d, one project, one URL — and every agent on the team stops guessing.
AGPL-3.0-or-later · Docker · PostgreSQL 16 + pgvector · Node.js 22