docs/en/guides/06-mcp-integration.md
OpenViking server has a built-in MCP (Model Context Protocol) endpoint, allowing any MCP-compatible client to access its memory and resource capabilities over HTTP — no additional processes needed.
pip install openviking or from source)openviking-server running (see Deployment Guide)The MCP endpoint is at http://<server>:1933/mcp, sharing the same process and port as the REST API.
The following platforms have been successfully integrated with OpenViking MCP:
| Platform | Integration Method |
|---|---|
| Claude Code | type: http |
| ChatGPT & Codex | Standard MCP config |
| Claude.ai / Claude Desktop | Via MCP-Key2OAuth proxy |
| Manus | Standard MCP config |
| Trae | Standard MCP config |
The MCP endpoint shares the same API-Key authentication system as the OpenViking REST API. Pass either header:
X-Api-Key: <your-key>Authorization: Bearer <your-key>No authentication is required in local dev mode (server bound to localhost).
Most MCP-compatible platforms (Trae, Manus, Cursor, etc.) use the standard mcpServers format:
{
"mcpServers": {
"openviking": {
"url": "https://your-server.com/mcp",
"headers": {
"Authorization": "Bearer your-api-key-here"
}
}
}
}
Claude Code requires "type": "http". Add via CLI:
claude mcp add --transport http openviking \
https://your-server.com/mcp \
--header "Authorization: Bearer your-api-key-here"
Or in .mcp.json:
{
"mcpServers": {
"openviking": {
"type": "http",
"url": "https://your-server.com/mcp",
"headers": {
"Authorization": "Bearer your-api-key-here"
}
}
}
}
Add --scope user to make the config global (shared across all projects).
Claude.ai and Claude Desktop Connector require MCP servers to use OAuth 2.1 authentication — API Keys cannot be passed directly.
We are evaluating built-in OAuth 2.1 authorization endpoints for openviking-server. The initial design includes:
ov otp) or REST API, then enter it on the OAuth authorization page — no external dependencies requiredThese approaches are currently in design review; implementation timeline is TBD.
Until official OAuth support is available, the community project MCP-Key2OAuth can proxy API Key auth as an OAuth flow:
https://your-server.com/mcp)⚠️ Disclaimer: MCP-Key2OAuth is a third-party community-maintained project. The OpenViking team makes no guarantees regarding its security, availability, or data handling. Please assess the risks before use. If you have concerns, consider waiting for the official OAuth implementation or deploying your own proxy.
Once connected, OpenViking exposes 9 tools:
| Tool | Description | Key Parameters |
|---|---|---|
search | Semantic search across memories, resources, and skills | query, target_uri (optional), limit, min_score |
read | Read one or more viking:// URIs | uris (single string or array) |
list | List entries under a viking:// directory | uri, recursive (optional) |
store | Store messages into long-term memory (triggers extraction) | messages (list of {role, content}) |
add_resource | Add a local file or URL as a resource | path, description (optional) |
grep | Regex content search across viking:// files | uri, pattern (string or array), case_insensitive |
glob | Find files matching a glob pattern | pattern, uri (optional scope) |
forget | Delete any viking:// URI (use search to find it first) | uri |
health | Check OpenViking service health | none |
Likely cause: openviking-server is not running, or is running on a different port.
Fix: Verify the server is running:
curl http://localhost:1933/health
# Expected: {"status": "ok"}
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.