[Bug]: openviking-mcp is not a general-purpose MCP bridge — default paths and schemas are hardcoded to the Cloudwise knowledge base with no disclosure

[aiformybiz]

Bug Description

The openviking-mcp package is published to PyPI and referenced in
community documentation as an MCP (Model Context Protocol) bridge for
the OpenViking context database. Inspection of the installed source
code reveals the package defaults are hardcoded to serve a specific
commercial knowledge base (Cloudwise) and is non-functional for
general OpenViking use. This is not documented anywhere in the README,
PyPI listing, or installation instructions.

A developer following available documentation in good faith will
encounter only silent failures and cryptic connection errors with no
indication that the package is scoped to a specific commercial product.

Additionally, two compounding connectivity bugs create a deadlock on
Windows 11 that produces a zero-success-rate installation experience
with no actionable diagnostic output at any failure point.

Steps to Reproduce

1. Follow OpenViking documentation to install and run the Docker
   container (ghcr.io/volcengine/openviking:v0.2.5)
2. Install the community MCP bridge: pip install openviking-mcp
3. Configure Claude Desktop claude_desktop_config.json per documented
   pattern with OPENVIKING_URL and OPENVIKING_API_KEY environment variables
4. Attempt any list_directory or query_kb call via the MCP bridge
5. Observe: all calls return either 401 Unauthorized or
   "Server disconnected without sending a response"

Expected Behavior

A package named openviking-mcp should function as a general-purpose
MCP bridge for any OpenViking instance, with:

• Configurable knowledge base paths with no vendor-specific defaults
• API key authentication support matching the server's security model
• Windows-compatible URL documentation (127.0.0.1 vs localhost)

Actual Behavior

The package is non-functional for any use case outside Cloudwise's
knowledge base. Three separate bugs compound to produce a
zero-success-rate installation experience on Windows 11.

BUG 1 — Hardcoded Cloudwise Paths

Inspection of site-packages/openviking_mcp/client.py reveals:

Line 233 — default path hardcoded to Cloudwise KB

path: str = "viking://cloudwise-kb"

Lines 102–195 — mock mode reveals the actual data model.

The package only models Cloudwise-specific namespaces:

"uri": "viking://cloudwise-kb/products"
"uri": "viking://cloudwise-kb/solutions"
"uri": "viking://cloudwise-kb/competition"
"uri": "viking://cloudwise-kb/usecases"

The Settings class in config.py confirms the store path default:

class Settings(BaseSettings):
url: str = "http://localhost:1933"
store: str = "viking://resources/cloudwise-kb" # Cloudwise default
tier_default: Literal["L0", "L1", "L2"] = "L1"
mock_mode: bool = False
# No api_key field exists in this class.

  class Config:
      env_prefix = "OPENVIKING_"

BUG 2 — OPENVIKING_API_KEY Is Silently Ignored

The Settings class contains no api_key field. The OPENVIKING_API_KEY
environment variable referenced in community integration guides is
silently discarded by pydantic-settings. The bridge sends all requests
with no Authorization header.

When root_api_key is configured in ov.conf (which the OpenViking server
requires for any non-localhost binding), every request returns 401
Unauthorized with no error message indicating that authentication is
unsupported by the bridge.

BUG 3 — IPv6/IPv4 Resolution Failure on Windows (Silent)

When server.host = "127.0.0.1" is set in ov.conf to satisfy the
server's security policy (required when root_api_key is absent), the
server binds to IPv4 only. On Windows 11, localhost resolves to ::1
(IPv6) by default. The bridge connects to http://localhost:1933, routes
to the IPv6 address, and receives an empty reply.

Error produced: "Server disconnected without sending a response"

This is a silent failure. No diagnostic output identifies the address
family mismatch.

DEADLOCK: Bugs 2 and 3 create a deadlock. With root_api_key set, the
bridge returns 401. Without it, the server requires 127.0.0.1 binding,
which triggers the IPv6 resolution failure. Neither state produces a
working connection.

Minimal Reproducible Example

# Confirm hardcoded path in installed package
import site, os
pkg = site.getsitepackages()[0]
path = os.path.join(pkg, "openviking_mcp", "config.py")
print(open(path).read())
# Look for: store: str = "viking://resources/cloudwise-kb"

# Confirm no api_key field in Settings
# Look for: absence of any api_key or authorization field

# Confirm IPv6 connection failure on Windows
# Run in PowerShell:
# curl.exe -v http://localhost:1933/health
# Observe: "Established connection to localhost (::1 port 1933)"
# Server bound to 127.0.0.1 will return: "Empty reply from server"

Error Logs

# With root_api_key set in ov.conf:
{"success": false, "error": "OpenViking API error: 401"}

# With root_api_key removed and host = 127.0.0.1:
{"success": false, "error": "Failed to connect to OpenViking: 
Server disconnected without sending a response."}

# curl.exe -v output confirming IPv6 resolution:
* Established connection to localhost (::1 port 1933) from ::1 port 60094
* Empty reply from server
curl: (52) Empty reply from server

OpenViking Version

v0.2.5

Python Version

3.14.0

Operating System

Windows

Model Backend

None

Additional Context

The package description and README contain no indication that the
default paths, mock data structure, and tool schemas are specific to
the Cloudwise commercial IT operations platform (cloudwise.com).
A developer using this package to connect a general-purpose OpenViking
instance will receive no error explaining why their data is
inaccessible — they will encounter only the connection failures
described above, against Cloudwise-specific paths they did not configure.

If this package is intended solely as a Cloudwise-specific integration,
that scope should be stated explicitly in the package description and
README so developers can make an informed decision before installation.

Suggested fixes:

1. Add api_key field to Settings and pass it as Authorization header in client.py
2. Make store path fully configurable with no vendor-specific default
3. Document the Windows localhost → 127.0.0.1 requirement in the README
4. Add a disclosure statement clarifying the intended scope of the package
5. Remove or clearly label hardcoded Cloudwise paths in mock mode

Note: A related Windows pip install bug (Makefile OS variable treated
as shell command rather than environment variable) was filed on
volcengine/OpenViking as Issue #563 and resolved via PR #571 on
2026-03-14. This report covers the remaining unresolved issues in
the MCP bridge layer.

Environment: Windows 11, Docker Desktop v4.64.0,
ghcr.io/volcengine/openviking:v0.2.5, openviking-mcp v0.1.0.
Source code analysis performed on installed package files at
C:\Python314\Lib\site-packages\openviking_mcp\

[qin-ctx]

Thanks for the detailed report and clear reproduction steps — every issue is well-identified.

These problems are real. To be frank, openviking-mcp was originally built quickly for a specific use case. Since then, the server side has gone through multiple iterations (API structure, authentication, configuration system have all changed significantly), but the MCP bridge layer didn't keep up, which led to the issues you encountered.

We're planning a refactor of the MCP Server. The main directions:

1. Remove all hardcoded paths — the store default will no longer point to any specific knowledge base, and mock data will use generic examples
2. Add authentication support — add an api_key field to Settings and pass it via the X-API-Key header, aligned with the server's auth model
3. Align with the latest server API — the implementation under examples/mcp-query/ in the repo has already been rewritten on FastMCP with query, search, and add_resource tools. We'll build on that to replace the outdated PyPI package
4. Improve Windows compatibility — document the 127.0.0.1 vs localhost difference explicitly in docs and default configs to prevent silent IPv6 failures

All five of your suggestions are reasonable and largely align with our refactor plan. If you're interested, PRs are very welcome — whether it's fixing existing issues or contributing to the redesign. We're also happy to discuss API design or implementation ideas in this issue or in discussions.

[mvanhorn]

Partially addressed in #691 - adds --api-key/OV_API_KEY and --default-uri/OV_DEFAULT_URI CLI flags to the in-repo MCP server, and fixes the localhost -> 127.0.0.1 issue in examples. The external openviking-mcp PyPI package is out of scope for this repo.