Repository navigation
Connecting a Client
StrataKB is a standard MCP server on the stdio transport. Your MCP client starts it as a subprocess and talks to it over stdin and stdout.
sequenceDiagram
participant C as MCP client
participant S as StrataKB
participant D as PostgreSQL
C->>S: start subprocess (uv run python -m stratakb)
S->>D: connect, update the schema
C->>S: initialize, tools/list
S-->>C: strata_* tools (answered at once)
S->>S: load embedding model in the background
C->>S: tools/call strata_ask
S->>D: hybrid search (waits for the model if still loading)
S-->>C: status, passages with citations
Add an entry like this to your client's MCP configuration. Many clients read a project-level .mcp.json; check your client's documentation for the file it uses.
{
"mcpServers": {
"stratakb": {
"command": "uv",
"args": ["run", "--directory", "/path/to/StrataKB", "python", "-m", "stratakb"],
"env": {
"DATABASE_URL": "postgresql://strata:strata_dev_password@127.0.0.1:5433/strata",
"READONLY_DATABASE_URL": "postgresql://strata_readonly:strata_readonly_dev_password@127.0.0.1:5433/strata",
"STRATA_USER": "alice",
"STRATA_ROLE": "viewer"
}
}
}
}- Replace
/path/to/StrataKBwith the folder you cloned. -
python -m stratakband thestratakbcommand start the same server;"args": ["run", "--directory", "/path/to/StrataKB", "stratakb"]works too. -
STRATA_USERis the name that appears in the audit log. The user record is created the first timestrata_whoamiis called. -
STRATA_ROLEisviewer,operatororadmin. See Roles and Audit. - Leave out
READONLY_DATABASE_URLif you don't need the SQL tools; without it they are not offered. - Keep this file out of version control if it holds real passwords.
The server answers the client at once: it connects to the database, updates the schema if needed, and then loads the embedding model in the background. The first search waits for the model; on the first run that includes the download of about 420 MB. If that first search times out, wait for the download to finish and ask again, or run uv run stratakb add on a folder once beforehand so the model is cached.
Ask your client to call strata_admin_health. It reports whether the database is reachable, whether pgvector is installed and whether all the schemas exist. It also shows the embedding model and vector column checks (embedding), whether the SQL tools are on (sql_tools), the local-only switch (local_only) and the providers that receive data (outbound). strata_whoami shows the user and role the server sees.
Settings come from, each overriding the one before: the defaults, your user-level config.env, the file named by STRATAKB_CONFIG, then environment variables, which include the env block above. ./.env is not read unless STRATAKB_CONFIG names it. Installation has the file locations, and the README has the full table. The ones you are most likely to change:
| Variable | Why you would change it |
|---|---|
ANTHROPIC_API_KEY |
Turns on query rewriting in strata_ask
|
QUERY_REWRITE_PROVIDER, QUERY_REWRITE_BASE_URL, QUERY_REWRITE_MODEL
|
Rewrite questions through a local or self-hosted chat model instead; see Asking and Searching |
EMBEDDING_BACKEND, EMBEDDING_BASE_URL, EMBEDDING_MODEL
|
Embed through OpenAI or any OpenAI-compatible server (Ollama, LM Studio, vLLM) instead of the local model |
STRATA_LOCAL_ONLY |
Refuse to start while anything would send content off this machine; see Where your data goes |
RERANKING_ENABLED |
Turn off the cross-encoder on slow machines |
LEARNING_ENABLED |
Stop recording interactions |
LOG_LEVEL |
DEBUG when you investigate a problem; logs go to stderr |
With EMBEDDING_BACKEND=openai and EMBEDDING_BASE_URL set, StrataKB embeds through any server that speaks the OpenAI embeddings API. Your documents and questions then go to that server and nowhere else; no OpenAI key is needed. For a local Ollama:
ollama pull nomic-embed-text # 768 dimensions, matches the default columnEMBEDDING_BACKEND=openai
EMBEDDING_BASE_URL=http://127.0.0.1:11434/v1
EMBEDDING_MODEL=nomic-embed-text
# EMBEDDING_API_KEY= # only if the server asks for a keyA local server that needs no key works as it is: with no key set, StrataKB sends the placeholder unused, which such a server ignores, and never falls back to OPENAI_API_KEY.
The URL ends in /v1. Vectors whose length differs from EMBEDDING_DIMENSIONS are refused with a message naming the setting. Once at startup, in the background, the server asks the embedding server for its model list and checks the vector column's size; strata_admin_health reports both under embedding (model and vector_column), and overall turns degraded when the model is not listed or the sizes differ. A server that cannot list its models shows unchecked. After pulling a model or resizing the column, restart StrataKB to check again.
Switching models means re-embedding every layer; see Layers and Presets.
Getting started
Using StrataKB
Reference
Help