This guide connects Claude Code, Cursor, Windsurf, and VS Code to a single Pyckle index so every tool searches the same semantic knowledge base.

Prerequisites

Pyckle installed
Two or more AI tools installed (Claude Code, Cursor, Windsurf, or VS Code)

Step 1: Understand How the Shared Index Works

Pyckle stores its vector index on disk at a fixed path — by default ~/.pyckle/indexes/. Every MCP server instance that points to the same path reads from and writes to the same ChromaDB collection. You don't sync anything. You just make sure each tool's MCP config points to the same directory.

The index is keyed by codebase path. If you index /home/you/myproject once, any tool with access to that index path can query it immediately.

Key Insight

The MCP server is stateless between calls. The index is the state. Point two servers at the same index directory and they behave identically — no syncing, no conflicts, no duplicated embeddings.

Step 2: Generate the Multi-Tool Export Config

Pyckle ships a CLI command that writes ready-to-paste MCP config blocks for every supported tool. Run it once from your project root. It reads your current index location and outputs JSON for each tool.

pyckle export-config --tools claude,cursor,windsurf,vscode --index-path ~/.pyckle/indexes/

The output looks like this:

{
  "claude_code": {
    "mcpServers": {
      "pyckle-mcp": {
        "command": "python",
        "args": ["-m", "pyckle_mcp.server"],
        "env": {
          "PYCKLE_INDEX_PATH": "/home/you/.pyckle/indexes/"
        }
      }
    }
  },
  "cursor": {
    "mcpServers": {
      "pyckle-mcp": {
        "command": "python",
        "args": ["-m", "pyckle_mcp.server"],
        "env": {
          "PYCKLE_INDEX_PATH": "/home/you/.pyckle/indexes/"
        }
      }
    }
  }
}

Try This

Pass --output configs/ to write each block to its own file: configs/claude.json, configs/cursor.json, etc. Easier to paste per tool.

Step 3: Apply the Config to Each Tool

Each tool has a different config file location. Paste the relevant block into each one. The PYCKLE_INDEX_PATH env var must be identical across all of them — that's the only constraint.

Claude Code — paste into ~/.claude/settings.json under mcpServers:

"pyckle-mcp": {
  "command": "python",
  "args": ["-m", "pyckle_mcp.server"],
  "env": {
    "PYCKLE_INDEX_PATH": "/home/you/.pyckle/indexes/"
  }
}

Cursor — open Cmd/Ctrl + Shift + J → MCP tab → paste the cursor block.

Windsurf — edit ~/.windsurf/mcp_config.json and merge the windsurf block into the mcpServers object.

VS Code (Copilot MCP) — add to your .vscode/settings.json under github.copilot.mcp.servers:

"pyckle-mcp": {
  "command": "python",
  "args": ["-m", "pyckle_mcp.server"],
  "env": {
    "PYCKLE_INDEX_PATH": "/home/you/.pyckle/indexes/"
  }
}

Warning

Do not use ~/ in the env var value inside JSON. Some tools don't expand tildes in env blocks. Use the full absolute path: /home/you/.pyckle/indexes/.

Step 4: Verify All Tools Hit the Same Index

After restarting each tool, confirm they're all reading the same collection. Call index_stats() from each tool's MCP interface and compare the chunk counts — they should match exactly.

From Claude Code:

index_stats()

Expected output:

{
  "status": "ready",
  "codebase_path": "/home/you/myproject",
  "chunks": 6412,
  "index_path": "/home/you/.pyckle/indexes/"
}

Run the same call from Cursor and Windsurf. If the chunk count differs, one tool is pointing at a different path. Go back to its config and fix the PYCKLE_INDEX_PATH value.

Key Insight

Chunk count is your ground truth. Same number across tools means same index. Any discrepancy means one server is reading a different directory or an unrelated codebase collection.

Step 5: Keep the Index Fresh Across Tools

You only need to re-index from one tool — whichever you're actively editing in. The index on disk updates immediately and every other tool picks up the changes on their next query. There's no replication step.

The fastest pattern: re-index after significant refactors, and call register_edit() after individual file changes so search routing stays accurate without a full re-index.

register_edit("/home/you/myproject/src/auth/middleware.py")

To re-index the full project when needed:

index_codebase("/home/you/myproject")

Try This

Add a git post-commit hook that calls register_edit() for each changed file. Every tool gets accurate routing automatically after every commit, with no manual step.

What's Next

Next Guide Set Up Pyckle in Cursor, Windsurf, or VS Code → Next Guide Register Edits for Smarter Routing → Next Guide Upgrade to Pro — Custom PyckLM Tuning →

Use One Index Across Multiple Tools