Security

Contextator is built for a specific deployment: a trusted team, on a private network or behind a reverse proxy. The dashboard has accounts and roles; the MCP endpoints have one door per project. Read this page before exposing it anywhere else.

---

The one thing to know

A new project is born token required: creating it mints a first token and shows the secret once, in the creation dialog, so its endpoint is closed from the first second. A project created before that became the default keeps whatever mode it already had — upgrading does not retroactively close or open an existing project. Either way, the MCP access panel on the project page is where the mode is set, and there are three of them: open, where the endpoint answers anyone; token required, after which a client must send Authorization: Bearer ctxm_… or be answered 401; or account required, where the project’s own memberships reach the endpoint through OAuth 2.1 and are checked on every request. See Projects for the switch and Connecting AI Clients for the client side.

A token is a credential for the endpoint, not an account. It carries no identity and no per-document rules, so whoever holds it reads everything indexed in that project, and dashboard roles do not reach /mcp/* at all.

So network position still decides most of it. An instance that leaves its projects open is readable by anyone who can reach it, whatever the dashboard says about who may see what: keep the port private, or put authentication in front of it.

The dashboard and the admin API are a separate door, and that one is always locked: they require a personal account. ADMIN_TOKEN is not that lock — it is machine access to /api/* for scripts — and neither of them protects /mcp/*. A project’s own tokens are the only thing that does. See Accounts and Permissions.

Operator checklist

1. Give each person their own account, and none to anyone who does not need one. The first is created at /setup with a one-time code; the rest come from Users in the top-right menu. A member account reaches only the projects you add it to — see Accounts and Permissions. On a plain-HTTP LAN address set AUTH_COOKIE_SECURE=0, or the browser drops the session cookie and nobody can sign in at all.
2. Keep ADMIN_TOKEN out of browsers, and unset it if nothing scripted needs the API. It acts with root permissions on every endpoint; treat it like a root password.
3. Set SECRET_KEY to 32+ random characters (openssl rand -hex 32) before adding a private git repository or a Notion integration. Store it somewhere other than your database backup.
4. Close the projects that should not be public. MCP access on the project page: token required, then New token once per client, or account required if the people who may read it already have accounts here. A project left open is readable by anyone who can reach its URL — see Projects.
5. Keep the port off the public internet, or terminate authentication in a reverse proxy — including for the projects you deliberately leave open. The default (CONTEXTATOR_BIND=127.0.0.1) already publishes the port on this machine only; 0.0.0.0 is the one setting that changes that, and is the moment to put a reverse proxy or a VPN in front. See Configuration.
6. Keep ALLOWED_DOC_ROOTS narrow. It is the boundary that decides which directories can be indexed.
7. Mount documentation read-only (:ro), as the shipped compose file does.
8. Scope source tokens tightly. A git token needs read access to the documentation repositories, nothing more.
9. Do not index secrets. Everything indexed is readable by every agent that can reach the endpoint — and by every holder of that project’s MCP tokens, which carry no per-document rules.

What is protected, and how

Putting authentication in front

Example with nginx Basic authentication, leaving the streaming transports intact:

location / {
    auth_basic           "Contextator";
    auth_basic_user_file /etc/nginx/.htpasswd;

    proxy_pass         http://127.0.0.1:3444;
    proxy_http_version 1.1;
    proxy_set_header   Host $host;
    proxy_set_header   X-Forwarded-Proto $scheme;
    proxy_buffering    off;
    proxy_read_timeout 1h;
}

# the webhook endpoint must stay reachable by the git host
location /api/webhooks/ {
    auth_basic off;
    proxy_pass http://127.0.0.1:3444;
}

Note that most MCP clients cannot send Basic credentials, so a proxy like this serves the dashboard more than it serves agents — and the dashboard already asks for an account, so a second prompt in front of it buys little. For /mcp/* itself a project token is the better fit, because it is an ordinary Authorization header that MCP clients do know how to set. Keep the proxy, or a mutual-TLS or VPN boundary, for the projects you deliberately leave open.

Behind a terminating proxy, set AUTH_COOKIE_SECURE=1 rather than relying on X-Forwarded-Proto.

Rotating things

Things Contextator does not defend against

• Prompt injection through documentation. If a document says “ignore your instructions and…”, the agent may read it. Contextator returns text faithfully; it does not sanitise intent. Treat your indexed corpus as trusted input.
• Rate limiting. Signing in is limited, per IP address and per account. Nothing else is: not the rest of /api/*, and not /mcp/*, where a token-protected project is no exception — a client holding a token can ask as often as it likes. The network boundary is the control.
• Two-factor authentication. There is none; a local account is a username and a password. Single sign-on is separate — an instance with an OIDC provider configured offers it alongside a password — and the record of who did what is the audit log at #/~audit in the dashboard, root and admin only, not just the server log.
• Per-user or per-document rules on /mcp/*. A project token is a credential for the whole endpoint, not an identity. It grants every document in the project, to whoever holds it, with no audit trail beyond this token was last used at. Dashboard roles do not reach /mcp/* — a viewer membership grants nothing there, and nothing narrows a token to part of a project. Bridging the two is planned and not built; until it is, give each client its own token and revoke the ones you no longer recognise.
• Hiding which projects exist. A token-protected project answers 401 where an unknown name answers 404, so anyone who can reach the server can still learn a project name.

Reporting a vulnerability

Report it privately to the repository owner rather than in a public issue.