OpenViking MCP Integration: Connect Claude, Cursor, and OpenClaw to Persistent Context

Mar 16, 2026

Purpose

When I use Claude Desktop or Cursor for coding, they forget everything between sessions. My preferences, project context, accumulated knowledge—all lost. Every conversation starts from zero.

OpenViking solves this as an MCP (Model Context Protocol) server. With a simple configuration, any MCP-compatible client gains persistent memory, shared resources, and semantic search. In this post, I’ll show you how to connect Claude Desktop, Cursor, and OpenClaw to OpenViking.

What is MCP?

Model Context Protocol (MCP) is becoming the standard for AI tool integration. It defines how AI assistants connect to external tools and data sources. Think of it as a universal plugin system for AI.

Without MCP, each AI tool has its own integration mechanism. With MCP, one server works everywhere:

┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
│ Claude Desktop  │     │     Cursor      │     │    OpenClaw     │
└────────┬────────┘     └────────┬────────┘     └────────┬────────┘
         │                       │                       │
         └───────────────────────┼───────────────────────┘
                                 │
                          MCP Protocol
                                 │
                      ┌──────────┴──────────┐
                      │   OpenViking MCP   │
                      │     Server         │
                      └────────────────────┘
                                 │
                      ┌──────────┴──────────┐
                      │  Persistent Memory  │
                      │  Resources & Search │
                      └────────────────────┘

Transport Modes: HTTP vs stdio

OpenViking supports two MCP transport modes:

	HTTP (SSE)	stdio
How it works	Single long-running server	Host spawns new process per session
Multi-session safe	Yes	No
Recommended for	Production, multi-agent	Single-session only

The stdio Problem

I learned this the hard way. When an MCP host spawns multiple stdio OpenViking processes, all instances compete for the same underlying data directory. This causes lock/resource contention.

Symptoms I encountered:

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

The solution: Use HTTP mode for any multi-session scenario.

Step 1: Start OpenViking Server

Before configuring any MCP client, I start the OpenViking server in HTTP mode:

openviking-server --config /path/to/config.yaml

By default, the server runs at http://localhost:1933.

I verify it’s running:

curl http://localhost:1933/health

Expected output:

{"status": "ok"}

For production, I use a process manager:

# Create systemd service
sudo systemctl start openviking
sudo systemctl enable openviking

Step 2: Configure Claude Code (CLI)

Claude Code CLI is the simplest to configure. I add OpenViking as an MCP server:

claude mcp add openviking \
  --transport sse \
  "http://localhost:1933/mcp"

To verify the configuration:

claude mcp list

Output:

openviking
  Transport: sse
  URL: http://localhost:1933/mcp

Step 3: Configure Claude Desktop

For Claude Desktop, I edit the configuration file directly.

macOS Location

~/Library/Application Support/Claude/claude_desktop_config.json

Windows Location

%APPDATA%\Claude\claude_desktop_config.json

Configuration

{
  "mcpServers": {
    "openviking": {
      "url": "http://localhost:1933/mcp"
    }
  }
}

After saving, I restart Claude Desktop to load the new configuration.

Step 4: Configure Cursor

Cursor uses the same MCP configuration format. I access it through Settings:

Open Cursor Settings
Navigate to MCP section
Add server configuration:

{
  "mcpServers": {
    "openviking": {
      "url": "http://localhost:1933/mcp"
    }
  }
}

Alternatively, I edit the config file directly at:

~/.cursor/mcp.json

Step 5: Configure OpenClaw

OpenClaw uses a similar configuration structure:

{
  "mcp": {
    "servers": {
      "openviking": {
        "url": "http://localhost:1933/mcp"
      }
    }
  }
}

stdio Mode (Single Session Only)

For single-session scenarios, I can use stdio mode. This is not recommended for most use cases:

claude mcp add openviking \
  --transport stdio \
  -- python -m openviking.server --transport stdio \
     --config /path/to/config.yaml

I only use stdio when:

Running a single agent instance
Testing locally
HTTP is not available

Available MCP Tools

Once connected, OpenViking exposes these tools to MCP clients:

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
`list_memories`	Browse stored memories
`list_resources`	Browse stored resources

Use Case: Claude with Persistent Memory

Here’s how I use OpenViking MCP with Claude Desktop:

Storing Preferences

I tell Claude:

“I prefer Python for data analysis tasks. Remember this.”

Claude calls add_memory to store this preference. In future sessions, when I ask about data analysis, Claude recalls “User prefers Python for data analysis.”

Building Project Knowledge

I add project documentation:

> Add this resource to OpenViking: /path/to/project/docs

Claude uses add_resource to index the documentation. Later, when I ask:

“How does the authentication module work?”

Claude searches the indexed documentation and provides accurate, project-specific answers.

Cross-Session Learning

Each session builds on the last:

Session 1: "I prefer tabs over spaces"
Session 2: "Always use TypeScript strict mode"
Session 3: "My preferred test framework is Vitest"

All these preferences accumulate in OpenViking, making Claude increasingly aligned with my coding style.

Use Case: Cursor with Project Knowledge

For Cursor, I use OpenViking for shared project knowledge:

Adding Project Context

> Add this repository to context: https://github.com/myorg/myproject

Cursor indexes the repository via OpenViking. When coding:

// Cursor suggests:
import { authenticate } from '@/lib/auth'
// It knows this exists from the indexed codebase

Multiple team members configure Cursor with the same OpenViking server:

Developer A: Adds project architecture docs
Developer B: Queries for "how does caching work"
Developer C: Gets accurate answer from shared knowledge

The entire team benefits from accumulated context.

Troubleshooting

`Collection 'context' does not exist`

Cause: Multiple stdio instances contending for the same data directory.

Fix: Switch to HTTP mode. This was the most common issue I encountered when I started.

# Stop all stdio instances
pkill -f "openviking.server"

# Start HTTP server
openviking-server

Connection Refused

Cause: Server not running or wrong port.

Fix: Verify server status:

curl http://localhost:1933/health

If this fails, start the server:

openviking-server

Authentication Errors

Cause: API key mismatch between client and server.

Fix: Check both configurations use the same API key:

{
  "embedding": {
    "dense": {
      "api_key": "your-api-key"
    }
  }
}

MCP Tools Not Appearing

Cause: Configuration not loaded or wrong URL.

Fix: Restart the MCP client and check the URL:

# Test MCP endpoint directly
curl http://localhost:1933/mcp

Search Returns Empty Results

Cause: No resources indexed yet.

Fix: Add resources first:

ov add-resource https://github.com/volcengine/OpenViking --wait

Best Practices

DO

Use HTTP mode for production

# Good: HTTP mode
openviking-server

# Bad for multi-session: stdio mode
python -m openviking.server --transport stdio

Index relevant resources

# Good: Project-specific resources
ov add-resource https://github.com/myorg/myproject --name "project-docs"
ov add-resource /path/to/api-specs --name "api-specs"

# Less effective: Generic resources
ov add-resource https://example.com/random-page

Use semantic search queries

Good: "how does the authentication middleware validate tokens"
Less effective: "auth"

DON’T

Don’t mix transport modes

# Bad: HTTP server + stdio clients = contention
openviking-server  # HTTP server running
claude mcp add openviking --transport stdio ...  # stdio client

Don’t skip the health check

# Bad: Assume server is running
# Good: Always verify
curl http://localhost:1933/health

Don’t use localhost in production

{
  "mcpServers": {
    "openviking": {
      "url": "https://openviking.your-domain.com/mcp"
    }
  }
}

Security Considerations

When exposing OpenViking over HTTP:

Use HTTPS in production - Encrypt traffic between client and server
Add authentication - Configure API keys or token-based auth
Network isolation - Run on internal network or VPN
Rate limiting - Prevent abuse of semantic search

server:
  host: 0.0.0.0
  port: 1933
  auth:
    enabled: true
    api_key: ${OPENVIKING_API_KEY}
  tls:
    enabled: true
    cert: /path/to/cert.pem
    key: /path/to/key.pem

Summary

In this post, I showed how to connect OpenViking as an MCP server to Claude Desktop, Cursor, and OpenClaw. The key points are:

Use HTTP mode (not stdio) for multi-session support
Configure the URL in each client’s MCP settings
Start the server before connecting clients
Verify with curl http://localhost:1933/health

The entire setup takes about 2 minutes per client. With persistent memory, your AI assistants learn from every session, building knowledge over time. No more starting from zero.

Final Words + More Resources

My intention with this article was to help others share my knowledge and experience. If you want to contact me, you can contact by email: Email me

Here are also the most important links from this article along with some further resources that will help you in this scope:

👨‍💻 OpenViking GitHub Repository
👨‍💻 Model Context Protocol Specification
👨‍💻 Claude Desktop Documentation

Oh, and if you found these resources useful, don’t forget to support me by starring the repo on GitHub!