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: Solarium

Setup

0. Prerequisites

Either of:

• Docker — Docker Desktop (macOS/Windows) or Docker Engine (Linux) with Compose v2. Check with docker compose version; if only docker-compose (with a hyphen) works, the install is too old — upgrade, or substitute docker-compose in the commands below.

• Python 3.11+ if you'd rather run it without Docker.

1. Get the code

git clone https://github.com/inteliScience/Vision4NX-Knowledge-Connector.git
cd Vision4NX-Knowledge-Connector

Every command in this README is run from that directory — it's the one holding docker-compose.yaml.

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

3. Configure

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

Both are required. The server refuses to start without them, and Compose won't even build if .env is missing entirely.

4. Run

Docker (recommended) — from the repo root:

docker compose up -d --build
docker compose logs -f    # first run: confirm it actually came up

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

Troubleshooting

docker compose up -d reports success even when the container crashes a second later, so check the logs before anything else:

docker compose ps        # STATUS "Restarting" = it's crash-looping
docker compose logs -f

After editing .env, restart to pick it up: docker compose up -d (--build is only needed when the code changes).

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.