Vectorize MCP Server

A Model Context Protocol (MCP) server that provides semantic search capabilities by connecting Claude Desktop to a Cloudflare Workers backend with Vectorize.

Architecture

This is a hybrid architecture - the MCP server runs locally and bridges Claude Desktop to a remote Cloudflare Workers backend.

Features

• Semantic Search Tool: Natural language search using vector similarity

• stdio Transport: Works with Claude Desktop and other MCP clients

• Remote Backend: Heavy lifting (embeddings, vector search) happens on Cloudflare Workers

• Type-safe: Full TypeScript implementation

Prerequisites

• Node.js 18+ installed

• Claude Desktop installed

• vectorize-mcp-worker deployed

Installation

1. Clone and install:

2. Build:

3. Configure Claude Desktop:

Edit your Claude Desktop config file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

• Windows: %APPDATA%\Claude\claude_desktop_config.json

Add this server:

4. Restart Claude Desktop

Usage

The server exposes one tool to Claude:

semantic_search

Search the knowledge base using semantic similarity.

Parameters:

• query (string, required): Natural language search query

• topK (number, optional): Number of results to return (default: 5)

Example in Claude Desktop:

Claude will automatically use the semantic_search tool and return results with similarity scores.

How It Works

1. Claude sends query to MCP server via stdio

2. MCP server forwards query to Vectorize Worker via HTTP

3. Worker generates embedding using Workers AI

4. Vectorize searches for similar vectors

5. Results flow back through MCP server to Claude

6. Claude synthesizes answer using the search results

Configuration

Change Backend URL

Edit src/index.ts and update the Worker URL:

Then rebuild:

Adjust Result Count

The default topK is 5. Users can override this:

Development

Run in development mode:

Build for production:

Test locally:

The server will output: Vectorize MCP server running on stdio

Example Queries

Try these in Claude Desktop:

Response Format

The tool returns JSON with:

• query: Original search query

• resultsCount: Number of results found

• results: Array of matches with:

  • id: Entry identifier

  • score: Similarity score (0-1, higher is better)

  • content: Actual content

  • category: Content category

Claude automatically parses this and presents it naturally.

Troubleshooting

Server not appearing in Claude Desktop:

1. Check the config file path is correct

2. Verify the absolute path to dist/index.js

3. Make sure you restarted Claude Desktop completely (quit, not just close)

4. Check Developer Console (Ctrl+Shift+I in Claude Desktop)

"Not connected" errors:

1. Ensure Worker is deployed and accessible

2. Check WORKER_URL in src/index.ts

3. Verify Worker has data populated (POST /populate)

No results returned:

1. Populate the Vectorize index using the Worker's /populate endpoint

2. Try broader search terms

3. Check Worker logs with wrangler tail

Technology Stack

• TypeScript: Type-safe development

• @modelcontextprotocol/sdk: Official MCP SDK

• Node.js: Runtime environment

• stdio transport: Standard MCP communication method

Related Projects

• vectorize-mcp-worker - Backend Worker (required)

• mcp-server-worker - Full HTTP-based MCP on Workers

Why This Architecture?

Advantages:

• Works with Claude Desktop (requires stdio)

• Backend runs on edge (fast, scalable)

• Can share Worker backend across multiple clients

• Heavy processing (embeddings, search) happens remotely

Tradeoffs:

• Requires both local server and remote Worker

• Extra network hop adds latency (~50-100ms)

• Need to keep local server running

For a fully remote solution, see mcp-server-worker.

License

MIT

Author

Daniel Nwaneri - GitHub | Upwork