Guides

Setup MCP

How to add vibe-hnindex to different AI tools. Most clients use JSON; Codex uses TOML, and VS Code uses a different JSON root key.

Configuration Template

Here's the standard config block you'll add to each tool:

{
  "mcpServers": {
    "vibe-hnindex": {
      "command": "npx",
      "args": ["-y", "vibe-hnindex"],
      "env": {
        "OLLAMA_URL": "http://localhost:11434",
        "OLLAMA_MODEL": "bge-m3:567m",
        "QDRANT_URL": "http://localhost:6333"
      }
    }
  }
}

For Qdrant Cloud, add QDRANT_API_KEY and use your HTTPS cluster URL. See the Installation guide for details.

Per-Platform Setup

Codex — CLI, IDE and desktop

Run the installer inside your project:

npx -y hnindex-cli init --mcp codex
npx -y hnindex-cli init-skill --target codex

The first command merges MCP into .codex/config.toml; the second installs an optional workflow skill in .agents/skills/use-vibe-hnindex. Existing settings and other MCP servers are retained; TOML formatting and comments may change.

[mcp_servers.vibe-hnindex]
command = "npx"
args = ["-y", "vibe-hnindex"]

[mcp_servers.vibe-hnindex.env]
HNINDEX_PROJECT_ROOT = "/absolute/path/to/project"

Replace the example root with your absolute project path. The installer handles Windows path escaping. Codex only loads project configuration for trusted projects; choose project trust through Codex, then restart or reconnect the client.

For user-wide setup, use codex mcp add vibe-hnindex -- npx -y vibe-hnindex or edit ~/.codex/config.toml. A project-scoped installation is useful for binding one repository.

Open the trusted project in Codex and use /mcp to inspect active servers. User-wide installations can also be checked with codex mcp list. Ask the agent to call workspace_context, then initialize index_code_graph. See official Codex MCP documentation and architecture diagrams.

Verify Your Setup

Restart your AI tool after editing the MCP config
Look for vibe-hnindex in your tool's MCP server list
Try indexing a project: Index the codebase at /path, name it test
Run diagnostics: diagnostics()

Common Issues

Ollama not reachable

Ensure ollama serve is running on the configured URL

Qdrant auth error (401)

Set QDRANT_API_KEY for Qdrant Cloud

npm install fails (Windows)

Use Node 22 or 24 or install VS Build Tools

Server not showing up

Check file path and JSON/TOML syntax; restart tool

Full troubleshooting: Troubleshooting Guide

PreviousArchitecture diagrams

NextPerformance