Skip to content

Self-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.

docs: add MCP integration guide (EN + ZH) (#518)

r266-tech277d6e21df91
diff --git a/docs/en/guides/06-mcp-integration.md b/docs/en/guides/06-mcp-integration.md
new file mode 100644
index 000000000..e85161017
--- /dev/null
+++ b/docs/en/guides/06-mcp-integration.md
@@ -0,0 +1,230 @@
+# MCP Integration Guide
+
+OpenViking can be used as an [MCP (Model Context Protocol)](https://modelcontextprotocol.io/) server, allowing any MCP-compatible client to access its memory and resource capabilities.
+
+## Transport Modes
+
+OpenViking supports two MCP transport modes:
+
+| | HTTP (SSE) | stdio |
+|---|---|---|
+| **How it works** | Single long-running server process; clients connect via HTTP | Host spawns a new OpenViking process per session |
+| **Multi-session safe** | ✅ Yes — single process, no lock contention | ⚠️ **No** — multiple processes contend for the same data directory |
+| **Recommended for** | Production, multi-agent, multi-session | Single-session local development only |
+| **Setup complexity** | Requires running `openviking-server` separately | Zero setup — host manages the process |
+
+### Choosing the Right Transport
+
+- **Use HTTP** if your host opens multiple sessions, runs multiple agents, or needs concurrent access.
+- **Use stdio** only for single-session, single-agent local setups where simplicity is the priority.
+
+> ⚠️ **Important:** When an MCP host spawns multiple stdio OpenViking processes (e.g., one per chat session), all instances 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. Switch to HTTP mode to resolve this. See [Troubleshooting](#troubleshooting) for details.
+
+## Setup
+
+### Prerequisites
+
+1. OpenViking installed (`pip install openviking` or from source)
+2. A valid configuration file (see [Configuration Guide](01-configuration.md))
+3. For HTTP mode: `openviking-server` running (see [Deployment Guide](03-deployment.md))
+
+### HTTP Mode (Recommended)
+
+Start the OpenViking server first:
+
+```bash
+openviking-server --config /path/to/config.yaml
+# Default: http://localhost:1933
+```
+
+Then configure your MCP client to connect via HTTP.
+
+### stdio Mode
+
+No separate server needed — the MCP host spawns OpenViking directly.
+
+## Client Configuration
+
+### Claude Code (CLI)
+
+**HTTP mode:**
+
+```bash
+claude mcp add openviking \
+ --transport sse \
+ "http://localhost:1933/mcp"
+```
+
+**stdio mode:**
+
+```bash
+claude mcp add openviking \
+ --transport stdio \
+ -- python -m openviking.server --transport stdio \
+ --config /path/to/config.yaml
+```
+
+### Claude Desktop
+
+Edit `claude_desktop_config.json`:
+
+**HTTP mode:**
+
+```json
+{
+ "mcpServers": {
+ "openviking": {
+ "url": "http://localhost:1933/mcp"
+ }
+ }
+}
+```
+
+**stdio mode:**
+
+```json
+{
+ "mcpServers": {
+ "openviking": {
+ "command": "python",
+ "args": [
+ "-m", "openviking.server",
+ "--transport", "stdio",
+ "--config", "/path/to/config.yaml"
+ ]
+ }
+ }
+}
+```
+
+### Cursor
+
+In Cursor Settings → MCP:
+
+**HTTP mode:**
+
+```json
+{
+ "mcpServers": {
+ "openviking": {
+ "url": "http://localhost:1933/mcp"
+ }
+ }
+}
+```
+
+**stdio mode:**
+
+```json
+{
+ "mcpServers": {
+ "openviking": {
+ "command": "python",
+ "args": [
+ "-m", "openviking.server",
+ "--transport", "stdio",
+ "--config", "/path/to/config.yaml"
+ ]
+ }
+ }
+}
+```
+
+### OpenClaw
+
+In your OpenClaw configuration (`openclaw.json` or `openclaw.yaml`):
+
+**HTTP mode (recommended):**
+
+```json
+{
+ "mcp": {
+ "servers": {
+ "openviking": {
+ "url": "http://localhost:1933/mcp"
+ }
+ }
+ }
+}
+```
+
+**stdio mode:**
+
+```json
+{
+ "mcp": {
+ "servers": {
+ "openviking": {
+ "command": "python",
+ "args": [
+ "-m", "openviking.server",
+ "--transport", "stdio",
+ "--config", "/path/to/config.yaml"
+ ]
+ }
+ }
+ }
+}
+```
+
+## Available MCP Tools
+
+Once connected, OpenViking exposes the following MCP tools:
+
+| Tool | Description |
+|------|-------------|
+| `search` | Semantic search across memories and resources |
+| `add_memory` | Store a new memory |
+| `add_resource` | Add a resource (file, text, URL) |
+| `get_status` | Check system health and component status |
+| `list_memories` | Browse stored memories |
+| `list_resources` | Browse stored resources |
+
+Refer to OpenViking's tool documentation for full parameter details.
+
+## Troubleshooting
+
+### `Collection 'context' does not exist`
+
+**Likely cause:** Multiple stdio MCP instances contending for the same data directory.
+
+**Fix:** Switch to HTTP mode. If you must use stdio, ensure only one OpenViking process accesses a given data directory at a time.
+
+### `Transport closed`
+
+**Likely cause:** The MCP stdio process crashed or was killed due to resource contention. Can also occur when a client holds a stale connection after the backend was restarted.
+
+**Fix:**
+1. Switch to HTTP mode to avoid contention.
+2. If using HTTP: reload the MCP connection in your client (restart the session or reconnect).
+
+### Connection refused on HTTP endpoint
+
+**Likely cause:** `openviking-server` is not running, or is running on a different port.
+
+**Fix:** Verify the server is running:
+
+```bash
+curl http://localhost:1933/health
+# Expected: {"status": "ok"}
+```
+
+### Authentication errors
+
+**Likely cause:** API key mismatch between client config and server config.
+
+**Fix:** Ensure the API key in your MCP client configuration matches the one in your OpenViking server configuration. See [Authentication Guide](04-authentication.md).
+
+## References
+
+- [MCP Specification](https://modelcontextprotocol.io/)
+- [OpenViking Configuration](01-configuration.md)
+- [OpenViking Deployment](03-deployment.md)
+- [Related issue: stdio contention (#473)](https://github.com/volcengine/OpenViking/issues/473)
diff --git a/docs/zh/guides/06-mcp-integration.md b/docs/zh/guides/06-mcp-integration.md
new file mode 100644
index 000000000..7ed728cda
--- /dev/null
+++ b/docs/zh/guides/06-mcp-integration.md
@@ -0,0 +1,230 @@
+# MCP 集成指南
+
+OpenViking 可以作为 [MCP (Model Context Protocol)](https://modelcontextprotocol.io/) 服务器使用,任何兼容 MCP 的客户端都可以访问其记忆和资源能力。
+
+## 传输模式
+
+OpenViking 支持两种 MCP 传输模式:
+
+| | HTTP (SSE) | stdio |
+|---|---|---|
+| **工作方式** | 单个长期运行的服务器进程;客户端通过 HTTP 连接 | 宿主为每个会话生成一个新的 OpenViking 进程 |
+| **多会话安全** | ✅ 是 — 单进程,无锁竞争 | ⚠️ **否** — 多进程争用同一数据目录 |
+| **推荐用于** | 生产环境、多 Agent、多会话 | 仅限单会话本地开发 |
+| **配置复杂度** | 需要单独运行 `openviking-server` | 零配置 — 宿主管理进程 |
+
+### 选择合适的传输模式
+
+- **使用 HTTP**:如果你的宿主会打开多个会话、运行多个 Agent,或需要并发访问。
+- **使用 stdio**:仅在单会话、单 Agent 的本地环境中,且追求简单时使用。
+
+> ⚠️ **重要提示:** 当 MCP 宿主为每个会话生成独立的 stdio OpenViking 进程时(例如每个聊天会话一个进程),所有实例会争用同一底层数据目录。这会导致存储层(AGFS 和 VectorDB)的 **锁/资源竞争**。
+>
+> 表现为以下误导性错误:
+> - `Collection 'context' does not exist`
+> - `Transport closed`
+> - 间歇性搜索失败
+>
+> **根因不是索引损坏** — 而是多个进程争用同一存储文件。切换到 HTTP 模式即可解决。详见[故障排除](#故障排除)。
+
+## 配置
+
+### 前提条件
+
+1. 已安装 OpenViking(`pip install openviking` 或从源码安装)
+2. 有效的配置文件(参见[配置指南](01-configuration.md))
+3. HTTP 模式需要:`openviking-server` 正在运行(参见[部署指南](03-deployment.md))
+
+### HTTP 模式(推荐)
+
+首先启动 OpenViking 服务器:
+
+```bash
+openviking-server --config /path/to/config.yaml
+# 默认地址:http://localhost:1933
+```
+
+然后配置你的 MCP 客户端通过 HTTP 连接。
+
+### stdio 模式
+
+无需单独启动服务器 — MCP 宿主直接启动 OpenViking。
+
+## 客户端配置
+
+### Claude Code (CLI)
+
+**HTTP 模式:**
+
+```bash
+claude mcp add openviking \
+ --transport sse \
+ "http://localhost:1933/mcp"
+```
+
+**stdio 模式:**
+
+```bash
+claude mcp add openviking \
+ --transport stdio \
+ -- python -m openviking.server --transport stdio \
+ --config /path/to/config.yaml
+```
+
+### Claude Desktop
+
+编辑 `claude_desktop_config.json`:
+
+**HTTP 模式:**
+
+```json
+{
+ "mcpServers": {
+ "openviking": {
+ "url": "http://localhost:1933/mcp"
+ }
+ }
+}
+```
+
+**stdio 模式:**
+
+```json
+{
+ "mcpServers": {
+ "openviking": {
+ "command": "python",
+ "args": [
+ "-m", "openviking.server",
+ "--transport", "stdio",
+ "--config", "/path/to/config.yaml"
+ ]
+ }
+ }
+}
+```
+
+### Cursor
+
+在 Cursor 设置 → MCP 中配置:
+
+**HTTP 模式:**
+
+```json
+{
+ "mcpServers": {
+ "openviking": {
+ "url": "http://localhost:1933/mcp"
+ }
+ }
+}
+```
+
+**stdio 模式:**
+
+```json
+{
+ "mcpServers": {
+ "openviking": {
+ "command": "python",
+ "args": [
+ "-m", "openviking.server",
+ "--transport", "stdio",
+ "--config", "/path/to/config.yaml"
+ ]
+ }
+ }
+}
+```
+
+### OpenClaw
+
+在 OpenClaw 配置文件(`openclaw.json` 或 `openclaw.yaml`)中:
+
+**HTTP 模式(推荐):**
+
+```json
+{
+ "mcp": {
+ "servers": {
+ "openviking": {
+ "url": "http://localhost:1933/mcp"
+ }
+ }
+ }
+}
+```
+
+**stdio 模式:**
+
+```json
+{
+ "mcp": {
+ "servers": {
+ "openviking": {
+ "command": "python",
+ "args": [
+ "-m", "openviking.server",
+ "--transport", "stdio",
+ "--config", "/path/to/config.yaml"
+ ]
+ }
+ }
+ }
+}
+```
+
+## 可用的 MCP 工具
+
+连接后,OpenViking 提供以下 MCP 工具:
+
+| 工具 | 说明 |
+|------|------|
+| `search` | 跨记忆和资源的语义搜索 |
+| `add_memory` | 存储新记忆 |
+| `add_resource` | 添加资源(文件、文本、URL) |
+| `get_status` | 检查系统健康状态和组件状态 |
+| `list_memories` | 浏览已存储的记忆 |
+| `list_resources` | 浏览已存储的资源 |
+
+完整参数详情请参考 OpenViking 的工具文档。
+
+## 故障排除
+
+### `Collection 'context' does not exist`
+
+**可能原因:** 多个 stdio MCP 实例争用同一数据目录。
+
+**解决方案:** 切换到 HTTP 模式。如果必须使用 stdio,请确保同一时间只有一个 OpenViking 进程访问给定的数据目录。
+
+### `Transport closed`
+
+**可能原因:** MCP stdio 进程因资源竞争而崩溃或被终止。也可能发生在后端重启后客户端持有过期连接时。
+
+**解决方案:**
+1. 切换到 HTTP 模式以避免竞争。
+2. 如果使用 HTTP:在客户端中重新加载 MCP 连接(重启会话或重新连接)。
+
+### HTTP 端点连接被拒绝
+
+**可能原因:** `openviking-server` 未运行,或运行在不同端口上。
+
+**解决方案:** 验证服务器是否正在运行:
+
+```bash
+curl http://localhost:1933/health
+# 预期返回:{"status": "ok"}
+```
+
+### 认证错误
+
+**可能原因:** 客户端配置与服务器配置中的 API 密钥不匹配。
+
+**解决方案:** 确保 MCP 客户端配置中的 API 密钥与 OpenViking 服务器配置中的一致。参见[认证指南](04-authentication.md)。
+
+## 参考
+
+- [MCP 规范](https://modelcontextprotocol.io/)
+- [OpenViking 配置](01-configuration.md)
+- [OpenViking 部署](03-deployment.md)
+- [相关 Issue:stdio 竞争问题 (#473)](https://github.com/volcengine/OpenViking/issues/473)