[Bug]: Multiple stdio MCP sessions can contend for the same OpenViking data directory and surface misleading errors

[Hilbert-beinghappy]

Bug Description

When OpenViking is used as an MCP server via stdio in a multi-session host (for example, a host that starts one MCP process per session), multiple OpenViking MCP instances can end up pointing to the same data directory at the same time.

In my case, this caused lock/resource contention in the shared storage layer. The resulting user-visible errors were misleading: instead of clearly reporting a lock/resource conflict, the client later surfaced errors such as Collection 'context' does not exist or Transport closed.

The root cause was not a broken OpenViking index. After switching the client from multiple stdio instances to a single shared HTTP MCP endpoint, the problem disappeared.

Steps to Reproduce

1. Configure an MCP host to launch OpenViking via stdio.
2. Open multiple sessions so that the host starts multiple OpenViking MCP processes.
3. Let all of them point to the same OpenViking config/data directory.
4. Call MCP tools such as search or add_resource.
5. Observe lock/resource contention and downstream failures.

In my setup, using a single shared HTTP MCP server instead of per-session stdio instances avoided the problem.

Expected Behavior

• OpenViking should either handle this situation safely, or fail early with a clear lock/resource contention error.
• The error should clearly indicate that multiple MCP server instances are competing for the same underlying resources.
• Documentation should clarify when stdio is appropriate and when a shared HTTP MCP server is the safer deployment mode.

Actual Behavior

• Multiple stdio OpenViking MCP instances ended up competing for the same shared data/storage resources.
• The visible errors were misleading, including Collection 'context' does not exist.
• After the backend service itself was repaired, raw HTTP MCP calls succeeded, but an already-open client session still reported Transport closed until the MCP bridge was reloaded or a new session was opened.

Minimal Reproducible Example

Example MCP host configuration pattern:
[mcp_servers.openviking]
type = "stdio"
command = "python"
args = ["server.py", "--transport", "stdio", "--config", "/path/to/ov.conf", "--data", "/path/to/data"]

Then start two or more independent sessions/clients that use the same configuration and the same OpenViking data directory, and call search.

As a workaround, this shared HTTP configuration worked reliably for me:
[mcp_servers.openviking]
url = "http://127.0.0.1:2033/mcp"

Error Logs

Collection 'context' does not exist
Transport closed

OpenViking Version

0.1.17

Python Version

3.12.7

Operating System

macOS

Model Backend

Other

Additional Context

I verified that the backend service itself was healthy by calling the MCP HTTP endpoint directly:

• /mcp initialize returned 200 OK
• /mcp tools/list succeeded
• /mcp tools/call(search) succeeded and returned results

This strongly suggests that the main issue was not a broken index, but transport/configuration conflict caused by multiple stdio MCP instances and, in some clients, stale MCP connections after the backend was restarted.

This may be especially relevant to the new MCP stdio support discussed in #305. Even if the stale-session part is partly host-side, clearer documentation and clearer lock/contention errors on the OpenViking side would still help a lot.

[ZaynJarvis]

please try to test this feature in latest version, now it's 0.2.5

openviking in stdio mcp is not a recommended usage before. different openviking instance would conflict on agfs. This might change but for multi-session / multi-instantce openviking sharing on one data folder is for now not supported. HTTP mode is the way to use it correctly. That's also the main reason #305 is not merged yet. <@zhoujh01 do we have update on this?>

I agree documentation and error messages should be improved to prevent multi-session use on stdio MCP.

[r266-tech]

Following up on @ZaynJarvis's feedback that documentation should be improved — I've drafted an MCP Integration Guide (EN + ZH) that covers:

1. Transport comparison table — HTTP vs stdio, when to use which
2. Multi-session caveat — clear warning about stdio lock contention, with symptoms and recommended fix
3. Step-by-step setup — for Claude CLI, Claude Desktop, Cursor, OpenClaw
4. Troubleshooting — common errors mapped to root causes

I'd like to submit this as a PR to docs/{en,zh}/guides/06-mcp-integration.md. However, my r266-tech/OpenViking repo is not a proper GitHub fork (can't create cross-repo PRs). Could a maintainer either:

• Give me fork access, or
• I can paste the full content here and someone can commit it?

Preview of key section (stdio caveat):

⚠️ Important: When an MCP host spawns multiple stdio OpenViking processes (e.g., one per chat session), all instances may compete for the same underlying data directory. This causes lock/resource contention in the storage layer (AGFS and VectorDB).

Symptoms include misleading errors such as:

• Collection 'context' does not exist
• Transport closed
• Intermittent search failures

The root cause is not a broken index — it is multiple processes contending for the same storage files.

Full draft (both languages): https://github.com/r266-tech/OpenViking/tree/docs/mcp-transport-guide/docs

[ZaynJarvis]

docs lgtm. fork doesn't need extra permission to submit PR. could you clearify what fork access is required?

[r266-tech]

@ZaynJarvis Thanks for the clarification! The issue is that r266-tech/OpenViking was created as a standalone repo (not via GitHub's Fork button), so GitHub doesn't recognize it as a fork of volcengine/OpenViking — cross-repo PRs require the head repo to be a registered fork.

I'll create a proper fork (r266-tech/OpenViking-fork or similar) and resubmit the docs PR from there. Should have it up shortly.