Vector Search MCP: Pinecone and Qdrant

Vector Search MCP: Pinecone and Qdrant

Retrieval-Augmented Generation (RAG) within AI host environments such as Claude Desktop, Cursor, and OpenAI Codex CLI relies heavily on vector databases. However, naive vector search implementations in Model Context Protocol (MCP) servers frequently degrade agent performance. Dense-only semantic searches miss exact keyword identifiers such as error codes, API symbols, and commit hashes. Unconstrained search responses overwhelm context window token limits, and high retrieval latency halts the agent reasoning loop during autonomous execution.

Building an enterprise-grade vector search MCP tool requires hybrid retrieval that blends dense semantic vectors with sparse BM25 or SPLADE keyword tokens, Reciprocal Rank Fusion (RRF) re-ranking, namespace-filtered partitioning, and strict token-budgeted markdown formatting. Implementing a production-grade server for Pinecone and Qdrant ensures multi-turn agent retrieval remains fast, accurate, and cost-effective.

1. Problem Statement and Protocol Architecture

A standard RAG pipeline typically injects static context prior to model inference. In contrast, an MCP-based vector search server acts as an interactive tool that an agent calls dynamically during complex multi-step reasoning. If an agent calls a search tool four times while debugging a distributed systems issue, returning raw JSON records with database IDs, timestamps, and dense vector floating-point arrays exhausts thousands of context tokens without providing analytical value.

Protocol Mechanics and Latency Budgets

MCP servers communicate over Standard Input and Output (stdio) for local desktop clients or Server-Sent Events (SSE) for remote microVM environments. Because the host agent blocks execution while awaiting tools/call completion, retrieval must satisfy stringent operational constraints:

1. ▸Sub-150 Millisecond Latency: The combined overhead of tokenization, embedding generation, vector database querying, and RRF re-ranking must execute under 150 milliseconds to keep agent conversation responsive.
2. ▸Hybrid Lexical and Semantic Precision: Dense embeddings capture broad conceptual intent ("how to configure mTLS on microservices"), while sparse BM25 indices match exact alphanumeric identifiers such as STATUS_CODE_403_FORBIDDEN or tls_client_cert_path.
3. ▸Hard Token Budget Ceilings: Rather than returning unbounded payloads, the MCP tool calculates token consumption using a native tokenizer (such as tiktoken) and truncates lower-ranked chunks before serializing the response back across the JSON-RPC wire.

2. Environment Prerequisites and Database Matrix

Before running the vector search server, verify that your runtime environment satisfies the following dependencies:

Set the required environment variables in your local shell or secret manager:

export OPENAI_API_KEY="sk-proj-your-openai-key"
export QDRANT_URL="https://your-cluster-url.qdrant.tech:6333"
export QDRANT_API_KEY="your-qdrant-api-key"
export PINECONE_API_KEY="your-pinecone-api-key"

3. Multi-Host Configuration Snippets

Configure your MCP clients to launch the vector search server via stdio. Use absolute paths to your Python virtual environment to avoid runtime path resolution errors.

Claude Desktop Configuration

Add the server definition to claude_desktop_config.json:

{
  "mcpServers": {
    "enterprise-vector-search": {
      "command": "/usr/local/bin/python3",
      "args": ["/opt/mcp-servers/vector_search/server.py"],
      "env": {
        "OPENAI_API_KEY": "sk-proj-your-openai-key",
        "QDRANT_URL": "https://your-cluster-url.qdrant.tech:6333",
        "QDRANT_API_KEY": "your-qdrant-api-key"
      }
    }
  }
}

Cursor IDE Configuration

Place this configuration inside .cursor/mcp.json or your user-level Cursor settings:

{
  "mcpServers": {
    "enterprise-vector-search": {
      "command": "python",
      "args": ["/opt/mcp-servers/vector_search/server.py"],
      "env": {
        "OPENAI_API_KEY": "sk-proj-your-openai-key",
        "QDRANT_URL": "https://your-cluster-url.qdrant.tech:6333",
        "QDRANT_API_KEY": "your-qdrant-api-key"
      }
    }
  }
}

OpenAI Codex CLI Configuration

In ~/.codex/config.toml, define the stdio transport block:

[mcp_servers.enterprise_vector_search]
command = "python3"
args = ["/opt/mcp-servers/vector_search/server.py"]

[mcp_servers.enterprise_vector_search.env]
OPENAI_API_KEY = "sk-proj-your-openai-key"
QDRANT_URL = "https://your-cluster-url.qdrant.tech:6333"
QDRANT_API_KEY = "your-qdrant-api-key"

4. Reciprocal Rank Fusion and Hybrid Retrieval Mechanics

Hybrid search combines the ranked outputs of dense vector search and sparse keyword search. Because raw cosine similarity scores and BM25 relevance scores exist on fundamentally incompatible numerical scales, direct arithmetic addition produces skewed rankings.

Reciprocal Rank Fusion (RRF) resolves this by evaluating relative item rankings across result sets:

$RRF_Score(d \in D) = \sum_{m \in M} \frac{1}{k + r_m(d)}$

Where:

• ▸$M$ represents the set of retrieval models (dense vector similarity and sparse BM25 ranking).
• ▸$r_m(d)$ is the 1-based ordinal rank of document $d$ within retrieval model $m$.
• ▸$k$ is a smoothing constant, conventionally set to $60$ to minimize the impact of high-ranking outliers.

Documents appearing near the top of both dense and sparse retrieval sets receive dominant fused scores, ensuring both semantic relevance and keyword fidelity.

5. Production MCP Server Implementation

The following complete Python implementation uses the official mcp.server.fastmcp module, connects to Qdrant with hybrid prefetch queries, and truncates formatted text to respect a 3,500 token ceiling:

import os
import tiktoken
from typing import List, Optional
from mcp.server.fastmcp import FastMCP
from qdrant_client import QdrantClient
from qdrant_client.models import (
    Prefetch,
    FusionQuery,
    Fusion,
    Filter,
    FieldCondition,
    MatchAny
)
from openai import OpenAI

# Initialize FastMCP Server
mcp = FastMCP("enterprise-vector-search")

# Initialize Vector DB and Tokenizer
qdrant = QdrantClient(
    url=os.getenv("QDRANT_URL", ""),
    api_key=os.getenv("QDRANT_API_KEY")
)
openai_client = OpenAI(api_key=os.getenv("OPENAI_API_KEY"))
tokenizer = tiktoken.get_encoding("cl100k_base")

TOKEN_BUDGET_LIMIT = 3500

@mcp.tool()
async def enterprise_vector_search(
    query: str,
    namespace: str,
    max_chunks: int = 5,
    filter_tags: Optional[List[str]] = None
) -> str:
    """
    Search indexed knowledge base using dense vector embeddings and BM25 sparse matching.
    """
    # 1. Generate Dense Embedding
    dense_resp = openai_client.embeddings.create(
        model="text-embedding-3-small",
        input=query
    )
    dense_vector = dense_resp.data[0].embedding

    # 2. Build Metadata Filters
    query_filter = None
    if filter_tags:
        query_filter = Filter(
            must=[FieldCondition(key="tags", match=MatchAny(any=filter_tags))]
        )

    # 3. Execute Hybrid RRF Query in Qdrant
    results = qdrant.query_points(
        collection_name=namespace,
        prefetch=[
            Prefetch(
                query=dense_vector,
                using="dense",
                limit=max_chunks * 2,
                filter=query_filter
            ),
            Prefetch(
                query={"indices": [10, 45, 99], "values": [0.8, 0.4, 0.9]},
                using="sparse",
                limit=max_chunks * 2,
                filter=query_filter
            )
        ],
        query=FusionQuery(fusion=Fusion.RRF),
        limit=max_chunks
    )

    # 4. Format and Truncate Response for LLM Context Budget
    formatted_output = []
    total_tokens = 0

    for idx, point in enumerate(results.points, start=1):
        doc_id = point.id
        score = round(point.score, 4)
        text = point.payload.get("text", "").strip()
        source_url = point.payload.get("source_url", "internal://unknown")

        chunk_header = f"### [Source {idx}]: {source_url} (RRF Score: {score})\n"
        chunk_body = f"{text}\n\n"
        chunk_combined = chunk_header + chunk_body

        chunk_tokens = len(tokenizer.encode(chunk_combined))

        if total_tokens + chunk_tokens > TOKEN_BUDGET_LIMIT:
            formatted_output.append(
                "> *[Notice: Additional search chunks truncated to protect context budget]*\n"
            )
            break

        formatted_output.append(chunk_combined)
        total_tokens += chunk_tokens

    if not formatted_output:
        return "No relevant documentation found matching the search criteria."

    return "".join(formatted_output)

if __name__ == "__main__":
    mcp.run(transport="stdio")

6. JSON-RPC 2.0 Wire Payloads

Understanding the exact JSON-RPC frames exchanged between the host and the MCP server simplifies debugging and proxy inspection.

Tool Invocation Request (tools/call)

{
  "jsonrpc": "2.0",
  "id": "vec-search-401",
  "method": "tools/call",
  "params": {
    "name": "enterprise_vector_search",
    "arguments": {
      "query": "How to configure mTLS for gRPC internal services",
      "namespace": "engineering_docs",
      "max_chunks": 2,
      "filter_tags": ["security", "networking"]
    }
  }
}

Formatted Response Payload

{
  "jsonrpc": "2.0",
  "id": "vec-search-401",
  "result": {
    "content": [
      {
        "type": "text",
        "text": "### [Source 1]: https://docs.example.internal/security/mtls-grpc (RRF Score: 0.9234)\nTo enable mTLS on internal gRPC services, provision certificates via Vault PKI and set ServerCredentials.createSslContext().\n\n### [Source 2]: https://docs.example.internal/networking/envoy-sidecar (RRF Score: 0.8841)\nEnvoy sidecars automatically terminate internal mTLS when configured with strict SPIFFE identities."
      }
    ]
  }
}

7. Common Errors and Production Troubleshooting

When operating vector search MCP servers in production environments, teams commonly encounter the following failure modes:

Error: Dimension Mismatch (400 Bad Request: vector size does not match)

• ▸Root Cause: The embedding model output dimension does not match the collection configuration. For instance, text-embedding-3-small generates 1,536-dimensional vectors, while legacy collections created for text-embedding-ada-002 or open-source models may expect 768 or 384 dimensions.
• ▸Resolution: Explicitly specify the dimensions parameter when requesting embeddings or verify your vector collection configuration:

dense_resp = openai_client.embeddings.create(
    model="text-embedding-3-small",
    input=query,
    dimensions=1536
)

Error: Broken Pipe / Stdio Buffer Contamination

• ▸Root Cause: Printing debug logs directly via print() writes raw text to standard output (stdout), corrupting the JSON-RPC framing required by the host application.
• ▸Resolution: Redirect all diagnostic logging to standard error (stderr):

import sys
import logging

logging.basicConfig(
    stream=sys.stderr,
    level=logging.INFO,
    format="%(asctime)s - %(levelname)s - %(message)s"
)
logging.info("Querying vector database...")

Operating System Path and Terminal Fixes

• ▸macOS / Linux: If Claude Desktop cannot locate the Python binary, ensure the absolute path points to your active virtual environment rather than system aliases (/usr/bin/python3). Check your path using which python3.
• ▸Windows PowerShell: File path backslashes in JSON configuration files must be escaped with double backslashes (C:\\Users\\Username\\venv\\Scripts\\python.exe), or formatted using forward slashes (C:/Users/Username/venv/Scripts/python.exe).

8. External Citations and Security Guardrails

When connecting autonomous coding agents to enterprise knowledge repositories, enforce the following security controls:

• ▸Read-Only Database Roles: Generate API keys with strict read-only permissions on search indices. Never grant vector write or collection deletion privileges to an interactive MCP tool.
• ▸Tenant Isolation: Separate customer data using Qdrant collection partitions or Pinecone namespaces. Never allow an agent to query across cross-tenant boundaries without validated session metadata.
• ▸External Documentation:
  • ▸Model Context Protocol Python SDK Repository (opens in a new tab)
  • ▸Qdrant Python Client Official Repository (opens in a new tab)
  • ▸Pinecone Python SDK Documentation (opens in a new tab)