Quick Start

Budget about ten minutes for this, most of which is the one-time embedding-model download.

You need: Docker with Compose, and a folder of Markdown files. That is all — the database ships inside the container.

1. Start the server

No repository clone needed — this pulls the published image, contextator/contextator:

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
docker compose logs -f          # wait for "embedding model ready"

The first start does two slow things once: it initialises the database, and it downloads the embedding model (~470 MB by default; see Embedding Models for the smaller option). Both are stored in Docker volumes, so every later start takes seconds.

By default the folder ./docs is mounted read-only into the container at /docs; it is created empty if it does not exist yet. Point it at your own documentation instead by setting it in .env before starting:

DOCS_HOST_PATH=/path/to/your/docs

2. Create your account

The dashboard needs an account, and a new instance has none, so it starts by asking for a one-time setup code. While no account exists the server prints it at every start — it is in the log you are already following:

┌─ Contextator first-run setup ───────────────────────────────────────────┐
│ No user accounts exist yet; the dashboard is waiting for its first one. │
│                                                                         │
│   Open   http://localhost:3444/setup                                    │
│   Code   KRTW-9MHD-2PQF                                                 │
│                                                                         │
│ A new code is printed on every start until that first account exists.   │
└─────────────────────────────────────────────────────────────────────────┘

Open http://localhost:3444/ — it sends you to /setup — and fill in the code, a username and a password of at least 12 characters. Case and dashes in the code do not matter. Create the root account signs you in, and the code stops working for good.

3. Create a project

Press New project (or just type n).

Press Create project. The project appears in the list and its status moves through queued → syncing → embedding → idle. A few hundred Markdown files take a minute or two on the first run; later runs only touch what changed.

A new project requires a token by default: creation hands you the first one — ctxm_… — shown once, in the dialog. Copy it now; it is not shown again. Skip the copy and you have not lost access — you can mint another token from MCP access on the project page at any time.

4. Connect your agent

Select the project and find the Connect an agent panel. The creation dialog showed the snippets with your new token filled in; the panel shows the same snippets again, with <your token> in its place — paste in the token you copied. For Claude Code:

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

For Cursor, put this in ~/.cursor/mcp.json (global) or .cursor/mcp.json (per repository):

{
  "mcpServers": {
    "demo-docs": {
      "url": "http://localhost:3444/mcp/demo",
      "headers": { "Authorization": "Bearer ctxm_9f3a…" }
    }
  }
}

Claude Desktop needs a stdio bridge; the snippet is on the Connecting AI Clients page along with everything else.

5. Ask a question

Ask your agent something your documentation answers:

How do I re-index a project?

The agent calls search_docs, gets back the most relevant excerpts with their file paths and heading breadcrumbs, and answers from them. If it needs the whole file it calls read_document. If it wants to know what exists at all, it calls list_topics. You do not have to tell it which tool to use — the server describes itself.

You can verify the endpoint without an agent at all — but only for a project whose MCP access is open, since npm run smoke does not send a token. From a source checkout:

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

What next

• Add more documentation. A project can hold several sources at once — see Document Sources.
• Keep it in sync automatically. A push webhook re-indexes the moment someone merges: Push Webhooks.
• Give the rest of the team accounts. Users in the top-right menu creates them; a member account reaches only the projects you add it to under Members on the project page — see Accounts and Permissions.
• Mint more tokens, or open the endpoint, as the project needs. A new project is already token required — the first token was minted and shown once when you created it — with open and account required the other two settings under MCP access; account required checks the project’s own memberships through OAuth 2.1. See Projects.
• Tune retrieval. CHUNK_MAX_TOKENS defaults to 96 because that is what measured best, not because it fits the model’s window; see Indexing.