Contextator

Contextator

Self-hosted MCP server that turns your documentation into one semantically searchable endpoint per project.

Give a project its document sources — mounted folders, git repositories, uploaded archives, a Notion workspace, a Confluence Cloud site or Data Center instance, a published documentation site — and it becomes its own Model Context Protocol endpoint that AI agents (Cursor, Claude Code, Claude Desktop, …) can search:

http://localhost:3444/mcp/<project-name>

It ships as one Docker container, published as contextator/contextator, that holds both the database and the app, and is free software under the AGPL-3.0-or-later with a commercial license available (License).

Features

• One URL per project, fully isolated. Each project has its own document collection and vector embeddings in PostgreSQL + pgvector. A client connected to /mcp/billing never sees /mcp/mobile.
• Many sources per project. A local directory, a git repository (or one subdirectory of it), an upload of files/folders/.zip/.tar.gz/.rar, a Notion workspace, a Confluence Cloud site or Data Center instance, or a published documentation site read from its sitemap.xml, combined into one searchable endpoint. See Document sources.
• 100 % local by default. Embeddings are generated on the CPU with transformers.js (Xenova/multilingual-e5-small, a retrieval model covering 100 languages incl. Turkish). Switch to OpenAI embeddings with two env vars.
• Admin dashboard at http://localhost:3444/ to manage projects and their sources — add a repository, drop a folder or an archive on the page, test a connection, trigger re-indexing and watch progress.
• Accounts and roles. People sign in with their own account. root and admin manage everything and everyone; a member sees only the projects it is assigned to, as a read-only viewer or an editor that adds sources, uploads files and re-indexes. Any account can mint its own named, scoped, revocable API token for a script or CI job; ADMIN_TOKEN still works too. See Accounts and permissions.
• A door on each MCP endpoint, with three settings. A new project requires a bearer token that your client sends as an ordinary header, and is handed its first one as it is created, shown once. Make it open if its documents should be readable by anyone who can reach the URL, or require an account and its access becomes the memberships you already manage. Browser-based connectors sign in through OAuth 2.1. See MCP access.
• Incremental indexing. Files are hashed; only changed files are re-embedded, removed files are deleted.
• More than Markdown. .html, .docx, .csv, .pdf, .pptx, .xlsx, .ipynb, .rst and .adoc/.asciidoc are converted to Markdown as they are indexed, so an agent reads a Word file or a PDF the way it reads a page of documentation. See File types.

Quick Start

Everything runs in a single container named contextator: PostgreSQL 16 + pgvector and the Node.js app, started and stopped together by a small entrypoint script. Data lives in Docker volumes and survives container removal (see Data and persistence). The published image is contextator/contextator; docker compose up -d pulls it, so the two files below — not the whole repository — are all a fresh install needs.

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

in .env, pick the code that /setup will ask for once:

SETUP_CODE=whatever-you-like

optional: point DOCS_HOST_PATH at your own docs (it defaults to ./docs, created empty if missing)

docker compose up -d docker compose logs -f # wait for "embedding model ready"

The port is published on `127.0.0.1` only. The dashboard and every MCP endpoint answer on this machine and nowhere else, so a container started on a laptop or an office server does not appear on the network it is plugged into. To publish it on the network deliberately, set CONTEXTATOR_BIND=0.0.0.0 in .env and put a TLS-terminating reverse proxy or a VPN in front of it — see Running behind a reverse proxy.

1. Create the first account. Open http://localhost:3444/setup, enter the SETUP_CODE you chose, and create the root account. The code exists so that nobody who reaches the server before you can claim it; it stops working the moment that account is created.

Left SETUP_CODE empty? The server generates one and prints it at every start until an account exists — it is in the log you are already tailing:

   ┌─ Contextator first-run setup ───────────────────────────────────────────┐

│ No user accounts exist yet; the dashboard is waiting for its first one. │ │ │ │ Open http://localhost:3444/setup │ │ Code K7QM-92QX-VBHT │ │ │ │ A new code is printed on every start until that first account exists. │ └─────────────────────────────────────────────────────────────────────────┘

2. Sign in at **http://localhost:3444/**.

1. Press New project (or n): name it demo, and for the directory point at one of your own subfolders under /docs — the host folder from DOCS_HOST_PATH is mounted there, so docs/handbook on the host is /docs/handbook here. Leaving the directory empty creates an empty project; add its sources afterwards with Add source.
2. Watch the project's status go indexing → idle in the list; the Document sources panel shows every source with its document count, last sync and any error.
3. Use the Connect an agent tabs (Claude Code, Cursor, Claude Desktop, and the deprecated legacy SSE) for copy-paste snippets. From a source checkout, the bundled smoke test does the same thing from the command line:

npm install && npm run smoke -- http://localhost:3444/mcp/demo "how do I re-index"

The first start initialises the database and downloads the embedding model (~470 MB for the default fp32 model, ~235 MB with EMBEDDING_DTYPE=fp16, ~120 MB with EMBEDDING_DTYPE=q8, ~90 MB for all-MiniLM-L6-v2) into the contextator-models volume; later starts take a few seconds.

Without Compose:

docker run -d --name contextator -p 127.0.0.1:3444:3444 \

-e SETUP_CODE=whatever-you-like \ -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

Building the image from source instead of pulling it: Build the image yourself.

Tags. latest is the newest stable release; 1 (from 1.0.0 on) tracks the newest release of the 1.x major line; 1.0 tracks the latest patch inside the 1.0.x line; 1.0.0 is one exact, immutable release. Pin a versioned tag for anything you upgrade deliberately by setting CONTEXTATOR_TAG in .env (e.g. CONTEXTATOR_TAG=1.0.0) and running docker compose up -d — this reads at every start, not only the first. Every one of those tags from 0.2.0 on has a -slim twin — latest-slim, 1-slim, 1.0-slim, 1.0.0-slim — which is described in Bringing your own PostgreSQL.

Usage

Point Claude Code, Cursor, Claude Desktop or any other MCP client at http://localhost:3444/mcp/ — the dashboard's Connect panel prints the exact snippet, token header included when the project requires one. For a project that requires a token:

claude mcp add --transport http demo-docs http://localhost:3444/mcp/demo   --header "Authorization: Bearer ctxm_9f3a…"

Four read-only tools are exposed: search_docs (hybrid search, ranked excerpts), list_topics (the indexed document list), read_document (one file's Markdown, by path or heading range) and whats_new (what was added, changed or removed since a point in time). A fifth, report_gap, lets an agent tell the maintainers what the documentation did not answer; it writes to its own table (reported_gaps), never to documentation, and is absent while the query log is off. Beside the tools, each project publishes its documents as MCP resources and two read-only prompts, answer_from_docs (argument question) and explore_topic (argument topic).

One URL, Streamable HTTP first. Streamable HTTP is the way to connect. The legacy HTTP+SSE transport is deprecated: it still answers on the same URL and keeps working, no removal date is set, and its responses carry a Deprecation: true header. The same URL also speaks the stateless MCP 2026-07-28 protocol beside 2025-11-25.

A project is a set of sources — a local directory, a git repository, an upload, a Notion workspace, a Confluence site or a documentation site — each added in the dashboard under its own name, so a file install.md in a source named handbook is searched and read as handbook/install.md. An agent can narrow a search to one release with search_docs(query: "rotate the signing key", version: "v3").

Everything else — the protocol eras, the source types, access modes and file types — is in Connecting AI clients, Document sources, MCP access and File types.

How It Works

Stack: TypeScript · Node.js 24+ · Fastify 5 · PostgreSQL 16 + pgvector · Drizzle ORM · @modelcontextprotocol/server (MCP TypeScript SDK 2.x) · @huggingface/transformers · unpdf / mammoth / turndown.

Each run syncs every source, hashes files to skip what has not changed, converts and chunks what has (frontmatter-aware, split at headings, a breadcrumb kept per chunk), then embeds each chunk and writes it beside a keyword index — search is hybrid, meaning and exact wording fused by rank, which is why an environment variable name finds its page as readily as a question does. A force re-index rebuilds everything beside the live index rather than replacing it first, so the project keeps answering while it runs. CHUNK_MAX_TOKENS defaults to a measured 96, not the model's much larger window — filling the window measures worse.

Full run mechanics, the chunk-budget measurement, hybrid search and rank fusion, and the cross-lingual search limit (measured, not fixed, with what to do instead): Indexing and Embedding Models.

Configuration

Everything is an environment variable; see .env.example for the full annotated list. The variables that most installs touch: