Installation & Configuration

Get started with MCP Probe Kit v3.3.0 in 5 minutes. Supports Cursor, Cline, and Claude Desktop

v3.3.0 MCP 2025-11-25 SDK 1.27.1

Choose Installation Method

No installation required, use the latest version directly:

JSON

{
  "mcpServers": {
    "mcp-probe-kit": {
      "command": "npx",
      "args": ["-y", "mcp-probe-kit@latest"]
    }
  }
}

Advantage:No manual updates needed, automatically uses the latest version on each startup

Install globally to system:

Bash

npm install -g mcp-probe-kit

Configuration file:

JSON

{
  "mcpServers": {
    "mcp-probe-kit": {
      "command": "mcp-probe-kit"
    }
  }
}

Note:Need to manually run npm update -g mcp-probe-kit to update version

Memory System Setup (Qdrant + Embedding)

If you want to use search_memory、 memorize_asset、 read_memory_asset、 scan_and_extract_patterns , you need to configure both a vector database and an embedding service.

Copy the files below into two folders, start both services, then paste the MCP config. No Ollama required.

Extended guide (troubleshooting, performance): docs/memory-local-setup.md · 中文

Ports

Service	URL
Qdrant HTTP	`http://127.0.0.1:50008`
Qdrant gRPC	`127.0.0.1:50009`
Nomic Embed	`http://127.0.0.1:50012`

0. Directory layout

Create two folders anywhere on your machine (example: ~/mcp-memory/):

mcp-memory/
├── qdrant/
│   ├── docker-compose.yml
│   ├── .env
│   ├── data/
│   └── snapshots/
└── nomic-embed/
    ├── docker-compose.yml
    └── .env

1. Qdrant (vector DB, port 50008)

qdrant/docker-compose.yml

docker-compose.yml

services:
  qdrant:
    image: qdrant/qdrant:latest
    container_name: qdrant
    restart: always
    env_file:
      - .env
    ports:
      - "50008:6333"
      - "50009:6334"
    volumes:
      - ./data:/qdrant/storage
      - ./snapshots:/qdrant/snapshots
    environment:
      - QDRANT__SERVICE__HTTP_PORT=6333
      - QDRANT__SERVICE__GRPC_PORT=6334
      - QDRANT__LOG_LEVEL=INFO
      - QDRANT__SERVICE__API_KEY=${QDRANT_API_KEY}
    healthcheck:
      test:
        - "CMD"
        - "bash"
        - "-c"
        - "exec 3<>/dev/tcp/127.0.0.1/6333 && printf 'GET /collections HTTP/1.1\r\nHost: localhost\r\napi-key: ${QDRANT_API_KEY}\r\nConnection: close\r\n\r\n' >&3 && IFS= read -r line <&3 && [[ \"$$line\" == *\"200\"* ]]"
      interval: 30s
      timeout: 10s
      retries: 5
      start_period: 30s

qdrant/.env

.env

# Generate: python -c "import secrets; print(secrets.token_urlsafe(32))"
QDRANT_API_KEY=change-me-to-a-long-random-string
QDRANT_URL=http://127.0.0.1:50008

Start Qdrant

PowerShell / Bash

cd qdrant
mkdir data snapshots 2>$null; mkdir -p data snapshots
docker compose up -d
docker compose ps

Verify Qdrant

curl

curl http://127.0.0.1:50008/collections \
  -H "api-key: YOUR_QDRANT_API_KEY"

When API key is enabled, all requests need header api-key. Dashboard: http://127.0.0.1:50008/dashboard

2. Nomic Embed / Infinity (embeddings, port 50012)

nomic-embed/docker-compose.yml

docker-compose.yml

services:
  nomic-embed:
    image: michaelf34/infinity:0.0.70
    container_name: nomic-embed
    restart: unless-stopped
    ports:
      - "50012:7997"
    volumes:
      - hf_cache:/app/.cache
    environment:
      INFINITY_API_KEY: ${INFINITY_API_KEY}
    command:
      - v2
      - --model-id
      - nomic-ai/nomic-embed-text-v1.5
      - --revision
      - main
      - --dtype
      - float32
      - --batch-size
      - "8"
      - --engine
      - torch
      - --port
      - "7997"
      - --no-bettertransformer
    healthcheck:
      test:
        - "CMD"
        - "curl"
        - "-f"
        - "http://127.0.0.1:7997/health"
      interval: 30s
      timeout: 10s
      retries: 5
      start_period: 120s

volumes:
  hf_cache:

nomic-embed/.env

.env

# Generate: python -c "import secrets; print(secrets.token_urlsafe(32))"
INFINITY_API_KEY=change-me-to-a-long-random-string

Start embedding service

PowerShell / Bash

cd nomic-embed
docker compose up -d
docker logs -f nomic-embed
# Wait for: ready to batch requests

Verify embeddings

curl

curl http://127.0.0.1:50012/health

curl http://127.0.0.1:50012/embeddings \
  -H "Authorization: Bearer YOUR_INFINITY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"nomic-ai/nomic-embed-text-v1.5","input":"hello world"}'
# Expect data[0].embedding length = 768

First start downloads the model (~2–5 min). Use POST /embeddings (not /v1/embeddings). Returns 768-dim vectors.

3. MCP client configuration

Cursor / Claude Desktop mcpServers

{
  "mcpServers": {
    "mcp-probe-kit": {
      "command": "npx",
      "args": ["-y", "mcp-probe-kit@latest"],
      "env": {
        "MEMORY_QDRANT_URL": "http://127.0.0.1:50008",
        "MEMORY_QDRANT_API_KEY": "same-as-qdrant-.env-QDRANT_API_KEY",
        "MEMORY_QDRANT_COLLECTION": "mcp_probe_memory",
        "MEMORY_EMBEDDING_PROVIDER": "openai-compatible",
        "MEMORY_EMBEDDING_URL": "http://127.0.0.1:50012/embeddings",
        "MEMORY_EMBEDDING_MODEL": "nomic-ai/nomic-embed-text-v1.5",
        "MEMORY_EMBEDDING_API_KEY": "same-as-nomic-embed-.env-INFINITY_API_KEY",
        "MEMORY_SEARCH_LIMIT": "3",
        "MEMORY_SUMMARY_MAX_CHARS": "280"
      }
    }
  }
}

Use the same keys as in qdrant/.env and nomic-embed/.env. Restart Cursor after saving.

Other embedding options

Option B: Qdrant + Ollama

docker run -d --name mcp-qdrant -p 6333:6333 qdrant/qdrant
ollama pull nomic-embed-text

"MEMORY_QDRANT_URL": "http://127.0.0.1:6333",
"MEMORY_EMBEDDING_PROVIDER": "ollama",
"MEMORY_EMBEDDING_URL": "http://127.0.0.1:11434/api/embeddings",
"MEMORY_EMBEDDING_MODEL": "nomic-embed-text"

Option C: Qdrant + hosted OpenAI-compatible API

"MEMORY_QDRANT_URL": "http://127.0.0.1:50008",
"MEMORY_EMBEDDING_PROVIDER": "openai-compatible",
"MEMORY_EMBEDDING_URL": "https://your-embedding-endpoint/v1/embeddings",
"MEMORY_EMBEDDING_API_KEY": "your-api-key",
"MEMORY_EMBEDDING_MODEL": "text-embedding-3-small"

Environment Variables

MEMORY_QDRANT_URL: Qdrant endpoint, required by all memory features
MEMORY_QDRANT_API_KEY: Optional Qdrant API key
MEMORY_QDRANT_COLLECTION: Collection name, default mcp_probe_memory
MEMORY_EMBEDDING_PROVIDER: ollama or openai-compatible
MEMORY_EMBEDDING_URL: Embedding API endpoint
MEMORY_EMBEDDING_API_KEY: Embedding API key, usually empty for Ollama
MEMORY_EMBEDDING_MODEL: Embedding model name, default nomic-embed-text
MEMORY_SEARCH_LIMIT: Default search result limit, default 3
MEMORY_SUMMARY_MAX_CHARS: Summary max characters, default 280

Behavior Notes

Memory writes require MEMORY_QDRANT_URL, MEMORY_EMBEDDING_URL and MEMORY_EMBEDDING_MODEL
Read-only memory access (such as read by ID) only requires MEMORY_QDRANT_URL
The first write auto-creates the Qdrant collection and uses Cosine
Vector dimension is inferred automatically from the first embedding response

Build from source code, suitable for developers:

1. Clone repository

Bash

git clone https://github.com/mybolide/mcp-probe-kit.git
cd mcp-probe-kit

2. Install dependencies and build

Bash

npm install
npm run build

3. Configuration file

JSON

{
  "mcpServers": {
    "mcp-probe-kit": {
      "command": "node",
      "args": ["/path/to/mcp-probe-kit/build/index.js"]
    }
  }
}

Tip:Windows users should use full path, e.g. D:/workspace/mcp-probe-kit/build/index.js

Note:After modifying code, need to re-run npm run build to compile

Windows Notes for Graph Tools

Graph-aware tools may have a slower first run on Windows because GitNexus is started through npx by default.

The first cold start may take 20+ seconds while npx checks or downloads dependencies.
Some GitNexus dependencies use tree-sitter native modules and may require Visual Studio Build Tools.
If your MCP client supports env, prefer a preinstalled gitnexus CLI and raise GitNexus timeouts.
Quick install Build Tools on Windows: winget install Microsoft.VisualStudio.2022.BuildTools

Quick install command:

winget install Microsoft.VisualStudio.2022.BuildTools

Example using a preinstalled gitnexus CLI:

JSON

{
  "mcpServers": {
    "mcp-probe-kit": {
      "command": "mcp-probe-kit",
      "env": {
        "MCP_GITNEXUS_COMMAND": "gitnexus",
        "MCP_GITNEXUS_ARGS": "mcp",
        "MCP_GITNEXUS_CONNECT_TIMEOUT_MS": "30000",
        "MCP_GITNEXUS_TIMEOUT_MS": "45000"
      }
    }
  }
}

Locate Configuration File

Find the corresponding configuration file based on your MCP client:

Configuration file path:

Path

%APPDATA%\Claude\claude_desktop_config.json

Example:C:\Users\YourName\AppData\Roaming\Claude\claude_desktop_config.json

Configuration file path:

Path

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

Create or edit opencode.json in project root, or globally at ~/.config/opencode/opencode.json

opencode.json

{
  "mcp": {
    "mcp-probe-kit": {
      "type": "local",
      "command": ["npx", "-y", "mcp-probe-kit@latest"],
      "enabled": true
    }
  }
}

💡 Note:OpenCode uses "environment" (not "env") for env vars, "mcp" (not "mcpServers"), and "command" as an array with "type": "local" required. See OpenCode MCP docs.

Verify Installation

After completing configuration, verify with the following steps:

Restart MCP client (Cursor / Cline / Claude Desktop)
Type in chat window:Please use gencommit tool to generate a test commit message
If it returns a commit message following Conventional Commits specification, installation is successful!

✅ Success example:AI returns something like feat: add user authentication message

❌ Common issues:

"Tool not found" → Check configuration file format
"Command not found" → Confirm Node.js is installed
Windows users → Ensure using npx method

Delegated Orchestration Protocol

start_* orchestration tools do not execute operations directly, but return an executable plan.

Key fields:mode: "delegated", steps[], outputs[]

Plan Example

{
  "mode": "delegated",
  "steps": [
    {
      "id": "spec",
      "tool": "add_feature",
      "args": { "feature_name": "user-auth" },
      "outputs": ["docs/specs/user-auth/requirements.md"]
    }
  ]
}

💡 Key point:Execute stepsin order, and ensure outputs files are actually written to disk

⚠️ Common Issues

Error message:

Error: Cannot find package 'yallist'

Solution:Clear npx cache

Windows CMD

rmdir /s /q %LOCALAPPDATA%\npm-cache\_npx

macOS/Linux

rm -rf ~/.npm/_npx

Then restart MCP client

Possible reasons:

Node.js version too low (requires >= 16.0.0)
Dependencies not installed or corrupted
Configuration file format error

Solution:

Check Node.js version:
```
node --version
```
If below v16, please upgrade Node.js
Clear cache and reinstall:
```
npm cache clean --force
```
Check if configuration file JSON format is correct

Affected tools:

code_insight, start_feature, start_bugfix, init_project_context

Typical error:

gyp ERR! find VS could not find a version of Visual Studio 2017 or newer to use
gyp ERR! find VS - missing any VC++ toolset

Common causes:

npx -y gitnexus@latest mcp may spend 20+ seconds checking or downloading dependencies on cold start.
GitNexus depends on tree-sitter native modules, which may require Visual Studio Build Tools on Windows.

Recommended actions:

Install Visual Studio Build Tools with the C++ workload.
Retry once after dependencies finish installing so the first cold start is not mistaken for steady-state latency.
If your client supports env, prefer a preinstalled gitnexus CLI and raise MCP_GITNEXUS_CONNECT_TIMEOUT_MS plus MCP_GITNEXUS_TIMEOUT_MS.