Agent KB MCP

An open-source Model Context Protocol (MCP) server that seamlessly maintains a PostgreSQL database of problems and solutions encountered by agents. When agents hit roadblocks, they can search the KB intuitively by semantic embedding, providing verified solutions injected directly into context without needing external human intervention.

Embeddings rely entirely on a local Ollama instance, guaranteeing air-gapped security and avoiding entirely the requirement for cloud-based cloud API keys.

Requirements

• Node.js >= 18
• Postgres 14+ with the pgvector extension installed
• Ollama running locally featuring your chosen embedding model pulled

Installation / Usage

The server acts as an standard MCP utility and is configurable without any heavy setups. All runtime variables are handled safely via arguments or explicit environment variables, preventing the leaking of hard-coded secrets.

No global installation is necessary. You can attach it safely utilizing npx:

npx agent-kb-mcp \
  --db-url "postgres://<user>:<password>@<host>:5432/<database>" \
  --ollama-model "nomic-embed-text" \
  --embedding-dims 768 \
  --ollama-url "http://localhost:11434"

Argument Setup

| Flag | Env Variable | Requirement | Description | |---|---|---|---| | --db-url | KB_DB_URL | Required | Postgres database connection URL | | --ollama-model | OLLAMA_MODEL | Required | Model used for embeddings | | --embedding-dims | EMBEDDING_DIMS| Required | Target matrix dimensionality mappings | | --ollama-url | OLLAMA_URL | Optional | Custom proxy URL endpoint | | --port | KB_PORT | Optional | Setup explicit SSE port | | --min-similarity| KB_MIN_SIMILARITY| Optional | Fallback vector similarity hit threshold |

MCP Usage (Claude / Cursor)

Update your standard MCP configuration .json (such as mcp.json):

{
  "servers": {
    "agent-kb": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "agent-kb-mcp",
        "--db-url", "postgres://user:password@localhost:5432/agentdb",
        "--ollama-model", "nomic-embed-text",
        "--embedding-dims", "768"
      ]
    }
  }
}

Note: For security reasons, please heavily substitute the real user/password string externally using environment variables if committing config blocks globally.