Set Up Pyckle in Cursor, Windsurf, or VS Code

This guide connects your already-indexed Pyckle codebase to Cursor, Windsurf, or VS Code so semantic search and session context work directly from your IDE.

Step 1: Export Your Pyckle MCP Config

Pyckle ships a ready-to-paste MCP config you drop into each IDE. Pull it from the CLI so you're working with the exact server path and API key tied to your account.

pyckle mcp export --format json

The output is a JSON object with a mcpServers key. Keep this terminal open — you'll paste sections of it into each IDE config below.

Step 2: Configure Cursor MCP Settings

Cursor reads MCP servers from ~/.cursor/mcp.json. If the file doesn't exist, create it. Paste the mcpServers block from Step 1 directly into this file.

{
  "mcpServers": {
    "pyckle-mcp": {
      "command": "python",
      "args": ["-m", "pyckle_mcp.server"],
      "env": {
        "PYCKLE_API_KEY": "pyk_live_your_key_goes_here"
      }
    }
  }
}

Restart Cursor after saving. Open the MCP panel via Settings → MCP and confirm pyckle-mcp shows a green connected status.

Step 3: Configure Windsurf MCP Settings

Windsurf uses a per-workspace MCP config at .windsurf/mcp.json inside your project root, or a global config at ~/.windsurf/mcp.json. The global config applies to all workspaces — use it unless you need per-project isolation.

mkdir -p ~/.windsurf
cat > ~/.windsurf/mcp.json << 'EOF'
{
  "mcpServers": {
    "pyckle-mcp": {
      "command": "python",
      "args": ["-m", "pyckle_mcp.server"],
      "env": {
        "PYCKLE_API_KEY": "pyk_live_your_key_goes_here"
      }
    }
  }
}
EOF

Open Windsurf, navigate to Extensions → MCP Servers, and hit Reload. The pyckle-mcp entry should appear with a connected indicator.

Step 4: Configure VS Code MCP Extension

VS Code requires the MCP Client extension (search the marketplace for "MCP Client"). After installing, it reads from your workspace .vscode/mcp.json or user settings. The workspace file is easier to version per project.

mkdir -p .vscode
cat > .vscode/mcp.json << 'EOF'
{
  "servers": {
    "pyckle-mcp": {
      "type": "stdio",
      "command": "python",
      "args": ["-m", "pyckle_mcp.server"],
      "env": {
        "PYCKLE_API_KEY": "pyk_live_your_key_goes_here"
      }
    }
  }
}
EOF

Note the key difference: VS Code MCP uses "servers" and requires "type": "stdio" — Cursor and Windsurf infer this. Open the Command Palette, run MCP: Connect to Server, and select pyckle-mcp.

Step 5: Test the Connection from Your IDE

Open the AI assistant panel in your IDE and call a Pyckle tool directly. The fastest check is index_stats() — it returns immediately and confirms both the connection and that your index is loaded.

index_stats()

You should see output like {"chunks": 6500, "status": "ready", "codebase": "/your/project"}. If you get a timeout or tool-not-found error, confirm the MCP server process is running with pyckle mcp status.

Once index_stats() responds, run a real search against your codebase to confirm the index is warm.

search_code("authentication middleware")