vision4nx-kb-mcp

MCP server (streamable HTTP) that exposes the Vision 4 NX knowledge base to any MCP client (Claude Code, Claude Desktop, and other MCP-capable clients).

It is a thin wrapper over the Vision 4 NX REST API — embedding, hybrid search and reranking all happen server-side, so this server needs no vector-DB access and no embedding model.

Tools

Related MCP server: Open WebUI Knowledge Base MCP Server

Setup

1. Get your access credentials

The VISION4NX_URL and VISION4NX_API_KEY for the Vision 4 NX instance are issued on request. Contact the Inteliscience team at info@inteliscience.net to obtain them.

The MCP server acts with this single service key — all clients share the KB permissions granted to it.

If tools return 403 or 404 errors, the access token may be missing permissions for a knowledge base — contact Inteliscience to have it adjusted.

2. Configure

cp .env.example .env   # set VISION4NX_URL and VISION4NX_API_KEY (from Inteliscience)

3. Run

Docker (recommended):

docker compose up -d --build

Plain Python (>=3.11):

python3.12 -m venv .venv
.venv/bin/pip install -e .
.venv/bin/vision4nx-kb-mcp
# or: .venv/bin/uvicorn vision4nx_kb_mcp.server:app --host 0.0.0.0 --port 8600

Health check: curl http://localhost:8600/health MCP endpoint: http://localhost:8600/mcp

Connecting clients

This server speaks streamable HTTP at http://localhost:8600/mcp. Clients that support HTTP/remote MCP connect to that URL directly; stdio-only clients need the mcp-remote bridge (shown below). No auth token is required — client auth is not enforced by this server.

Claude Code:

claude mcp add --transport http vision4nx-kb http://localhost:8600/mcp

Claude Desktop: two ways, depending on your version.

• Custom connector (if available): Settings → Connectors → Add custom connector, name it Vision 4 NX KB, URL http://localhost:8600/mcp, save and enable.

• Config file (works everywhere, needs Node.js): the desktop config only launches stdio commands, so bridge the HTTP endpoint with mcp-remote. Edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

  {
    "mcpServers": {
      "vision4nx-kb": {
        "command": "npx",
        "args": ["-y", "mcp-remote", "http://localhost:8600/mcp"]
      }
    }
  }

  Then fully quit and reopen Claude Desktop (Cmd+Q / quit from the tray — closing the window is not enough).

Vision 4 NX itself (use the KB tools from chats): Admin Settings → External Tools → add a tool server of type MCP with URL http://localhost:8600/mcp (from inside the compose stack: the container-network URL).

Any other MCP client: point it at http://localhost:8600/mcp with transport Streamable HTTP. If the client only supports stdio, wrap it the same way Claude Desktop's config file does: npx -y mcp-remote http://localhost:8600/mcp.

MCP Inspector (debugging):

npx @modelcontextprotocol/inspector
# transport: "Streamable HTTP", URL: http://localhost:8600/mcp

Deploying next to the Vision 4 NX stack

Uncomment the networks block in docker-compose.yaml, verify the network name (docker network ls), and point VISION4NX_URL at the app container (http://vision4nx:8080). Optionally drop the published port and proxy /mcp through the existing nginx instead.

Environment variables

Tests

Opt-in e2e test against a running server:

pip install -e '.[dev]'
MCP_SERVER_URL=http://localhost:8600/mcp pytest tests/test_e2e.py

Compatibility

Built against the Vision 4 NX backend, which paginates GET /api/v1/knowledge/ and pins mcp==1.26.0. The paginated-list handling falls back to an unpaginated response shape automatically.