Skip to content

Connecting a Client

boudou edited this page Nov 4, 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
    S->>S: load embedding model (downloads on first run)
    C->>S: initialize, tools/list
    S-->>C: strata_* tools
    C->>S: tools/call strata_ask
    S->>D: hybrid search
    S-->>C: chunks, sources, confidence
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.
  • STRATA_USER is the name that appears in the audit log. A user is created on first connection.
  • STRATA_ROLE is viewer, operator or admin. See Roles and Audit.
  • Keep this file out of version control if it holds real passwords.

Startup time

At startup the server connects to the database and loads the embedding model. On the first run the model also downloads. If your client gives up before the server is ready, raise its MCP startup timeout, or run one search from the command line first 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. strata_whoami shows the user and role the server sees.

Settings

All settings are environment variables. You can put them in the env block above or in .env. 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
EMBEDDING_BACKEND, OPENAI_API_KEY Use OpenAI embeddings instead of the local model
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

Clone this wiki locally