Skip to content

Connecting a Client

boudou edited this page Nov 5, 2026 · 9 revisions

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
Loading

Configuration

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/StrataKB with the folder you cloned.
  • python -m stratakb and the stratakb command start the same server; "args": ["run", "--directory", "/path/to/StrataKB", "stratakb"] works too.
  • STRATA_USER is the name that appears in the audit log. The user record is created the first time strata_whoami is called.
  • STRATA_ROLE is viewer, operator or admin. See Roles and Audit.
  • Leave out READONLY_DATABASE_URL if 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.

Startup time

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.

Check the connection

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

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

Embeddings from a model server

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 column
EMBEDDING_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 key

A 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.

Clone this wiki locally