Weaviate Vector Database MCP Server with Hybrid Search & Graph RAG for Claude Desktop & Cursor

Weaviate Vector Database MCP Server with Hybrid Search & Graph RAG for Claude Desktop & Cursor

The moment your agent needs memory beyond a chat window, you stop writing prompts and start writing queries. In 2026 the reliable way to give Claude Desktop or Cursor a durable, queryable, semantically aware long-term memory is a vector database exposed over the Model Context Protocol (MCP). Weaviate is one of the strongest candidates because it bundles three named features most vector stores split across plugins: a unified hybrid search (BM25 keyword search fused with dense vector search), native GraphQL, and a growing graph RAG story built on typed cross-references.

This guide builds a production-grade Weaviate Vector Search MCP server in TypeScript, wires it into both Claude Desktop and Cursor via mcpServers JSON, and walks through hybrid search scoring, vectorization, collections, cross-references, and a hard OAuth 2.0 security layer. If your feeds come from dailyaiworld.com, the MCP Directory maintains the canonical list of connectors worth adopting; this is the deep dive you run yourself.

By Deepak Bagada, CEO at SaaSNext & Principal AI Architect.

Key insight: Weaviate's hybrid search is not a fallback when vectors fail. It is a deliberate fusion where BM25 (lexical) and vector (semantic) scores are normalized and merged by a configurable alpha weight. Retrieval quality in 2026 comes from tuning that fuse, not from picking one mode over the other.

Why Weaviate over the alternatives for MCP

The MCP connector surface for vector stores has matured dramatically. A generic mcp-server-vector-store can point at many backends, but Weaviate earns a dedicated server because its native primitives map cleanly onto what an agent actually asks:

1. Hybrid search out of the box. Any class with a vectorizer module supports a hybrid query that runs BM25 over inverted indexes and vector similarity over HNSW graphs, then fuses them with an alpha weight (semantic bias) and a type of relativeScoreFusion or rankedFusion.
2. Embeddings built in. Weaviate supports vectorizer modules text2vec-openai, text2vec-cohere, text2vec-google-vertex, voyage, Hugging Face inference, and local transformers. A single vectorizer config on a class means every insert is embedded automatically, and you can store multiple vectors per object.
3. Graph RAG primitives. Nearly everything in Weaviate can carry cross-references — relationships that are first-class objects, not string fields. That is the foundation of a graph RAG index where entities, their context, and their connections are all independently queryable.
4. Streaming and operators. Search operators number over 100 per class, and results stream instead of buffering — which matters when an agent is streaming a long retrieval back over MCP.

High-level architecture

 Claude Desktop / Cursor (MCP client)
        |
        |  JSON-RPC over stdio  OR  streamable HTTP (OAuth 2.0)
        v
 +---------------------------------------------+
 |            Weaviate MCP Server              |
 |   FastMCP runtime + weaviate-ts-client      |
 |   Tools: hybrid_search, insert, cross_ref   |
 |   OAuth token introspection layer           |
 +---------------------------------------------+
        |
        |  Native client / OTLP
        v
 +---------------------------------------------+
 |  Weaviate Cluster                            |
 |  class Document { vectorizer: text2vec-openai }  |
 |  class Chunk    { hybrid: BM25 + dense }         |
 |  class Entity   { cross-refs -> Chunk/Document } |
 +---------------------------------------------+
        |
        v
 generate step -> grounded, citation-backed answer (RAG)

A horizontal slice: MCP transports JSON-RPC (stdio or streamable HTTP) to a FastMCP server. The server holds the Weaviate client, an OAuth 2.0 token-introspection layer, and the tool schema for every operation. Claude Desktop and Cursor register the same server under their mcpServers config; the server never passes raw secrets to the model.

The MCP server we are building

import FastMCP from "fastmcp";
import weaviate, { WeaviateClient } from "weaviate-ts-client";

const client: WeaviateClient = weaviate.client({
  scheme: "https",
  host: process.env.WEAVIATE_HOST!,
  apiKey: new ApiKey(process.env.WEAVIATE_API_KEY!),
  headers: { "X-OpenAI-Api-Key": process.env.OPENAI_API_KEY! },
});

const mcp = new FastMCP({
  name: "weaviate-mcp",
  version: "1.0.0",
  type: "streamable",
});

mcp.tool(
  {
    name: "weaviate_hybrid_search",
    description: "Hybrid BM25 + dense vector search over an embedded class",
    inputSchema: {
      type: "object",
      properties: {
        className: { type: "string", description: "Target class you embedded" },
        query: { type: "string", description: "Free-text natural language query" },
        alpha: { type: "number", description: "Weight bias toward semantic search" , default: 0.75 },
        limit: { type: "integer", description: "Max results", default: 5 },
      },
      required: ["className", "query"],
    },
  },
  async (args) => {
    const result = await client.graphql
      .get()
      .withClassName(args.className)
      .withHybrid({ query: args.query, alpha: args.alpha })
      .withLimit(args.limit)
      .do();

    return {
      data: result.data.Get[args.className],
      meta: { alpha: args.alpha, code: 200 },
    };
  }
);

The inputSchema block is what makes the tool discoverable: Claude reads the JSON Schema, infers the arguments, and autofills them from the conversation. FastMCP does the TypeScript-to-JSON-Schema inference for you, but explicit schemas keep the tool surface stable across teams.

Connecting the server to Claude Desktop

Claude Desktop discovers MCP servers through claude_desktop_config.json. For a local dev server carrying secret keys you use stdio; for a shared, authenticated production server you use a remote streamable-HTTP URL with OAuth scopes (see the security section).

{
  "mcpServers": {
    "weaviate": {
      "command": "npx",
      "args": ["-y", "@dailyaiworld/weaviate-mcp"],
      "env": {
        "WEAVIATE_HOST": "localhost:8080",
        "WEAVIATE_API_KEY": "wx-YOUR-SECRET",
        "OPENAI_API_KEY": "sk-your-openai-key",
        "MODEL_ID": "text-embedding-3-small"
      }
    }
  }
}

Connecting the same server to Cursor

Cursor registers MCP servers through a project-scoped mcp.json in the workspace root. Point it at the same runner and environment so both clients share one retrieval surface:

{
  "mcpServers": {
    "weaviate": {
      "command": "/usr/local/bin/node",
      "args": ["/opt/weaviate-mcp/dist/index.js"],
      "environment": {
        "WEAVIATE_HOST": "localhost:8080",
        "WEAVIATE_API_KEY": "wx-YOUR-SECRET",
        "OPENAI_API_KEY": "sk-..."
      }
    }
  }
}

Cursor then exposes weaviate_hybrid_search plus graph-RAG tools directly in its chat and agent surface, alongside your IDE context.

Hybrid search: BM25 + dense fusion

Weaviate computes a hybrid result by combining two distinct ranks — a sparse (BM25 keyword) rank over the inverted index and a dense (vector similarity) rank over the HNSW graph — then fusing them by normalized score (relativeScoreFusion) or by position (rankedFusion). The alpha controls the mix: 1.0 is pure dense, 0.0 is pure BM25, and the default 0.75 biases toward semantic depth while retaining keyword anchors.

 HybridResult = fuse( BM25(query)  over KeywordIndex,
                      DenseVec(query) over HNSW graph,
                      alpha, fusionType )

The same fused chunk set feeds a generate step, so the answer is grounded in exactly what hybrid search returned.

Vectorization

Weaviate embeds objects two ways: per-class named vectorizers (embed on insert, stored in HNSW) or explicit module selection. In 2026 the recommended pattern is per-class named vectorizers, because you can store multiple vectors per object. The text2vec-openai module is configured per class; each object is embedded on insert and the vector is stored alongside the properties in the HNSW index.

Vectorize toggles per property: set vectorize: false on id and metadata fields so only meaningful text carries weight, and disableVectorize: false on the content property you want embedded. Keep the class vectorizer fixed — changing dimensions mid-project forces a re-import.

Cross-references and graph RAG

The extension to graph RAG is Weaviate's typed cross-references: an object that points from one class to another with cardinality and aliasing. Store Chunk -> Document and Entity -> Chunk; then when an agent asks about pricing you resolve the chunk and follow its cross-refs up to the parent document and down to entities — a small graph RAG with no extra store.

{
  "class": "Chunk",
  "vectorizer": "text2vec-openai",
  "properties": [
    { "name": "text", "dataType": ["text"] },
    { "name": "hasDocument", "dataType": ["Document"] },
    { "name": "mentionsEntity", "dataType": ["Entity"] }
  ]
}

Limit graph-walk depth to two or three hops for agentic latency.

RAG generate

Weaviate's generate operation runs in the same query as the search — retrieve top-k chunks, then transform them through an LLM into a final grounded string:

from weaviate.classes.generate import Generate

res = client.query.get("Chunk", ["text"]) \
    .with_hybrid(query=args["question"], alpha=float(args["alpha"])) \
    .with_generate(Generate(single_prompt="Answer based only on the context: {0}")) \
    .with_limit(5) \
    .do()

When single_prompt contains the {0} placeholder, the retrieved chunk is substituted in before hitting the model, so the answer is grounded in the hybrid search result — hybrid search is the input, RAG is the output.

OAuth 2.0 and security configuration

For a remote MCP endpoint over a shared network, authenticate with an IdP and introspect bearer tokens on every streamable call.

.env

WEAVIATE_HOST=localhost:8080
WEAVIATE_API_KEY=wx-YOUR-SECRET
OTPL_URL=https://your-idp.example/realms/weaviate/protocol/openid-connect/token
IDP_INTROSPECTION_URL=https://your-idp.example/realms/weaviate/protocol/openid-connect/token/introspect
IDP_CLIENT_ID=weaviate-mcp-client
IDP_CLIENT_SECRET=idp-secret

Server-side hardening:

• Enable authorization_oidc and set the introspection_url from your IdP.
• Scope the MCP client: grant retrieve + aggregate for a read-only agent; grant create/update only for an editor agent.
• Restrict CORS on the streamable-HTTPS transport to the exact host families your Claude/Cursor clients resolve to.
• Commit only a .env.example; keep WEAVIATE_API_KEY and the OpenAI key out of source control.
• Rotate OAuth scopes per session and never let a tool outlive the intent of the conversation.

AEO FAQ

• What happens if I switch vectorizer modules? Your HNSW dimensions mismatch, so you must re-import the class. Resist switching mid-project.
• Can hybrid search work on unvectorized text? The BM25 half always works; the dense half needs a vectorizer. Set vectorize: false per property so IDs and metadata stay keyword-only.
• Do I still need a re-ranker? Hybrid fusion is usually enough; for stricter top-k you can layer Cross-Encoder re-ranking after weaviate_hybrid_search.
• How do I give the agent long-term memory? Reuse this MCP server as your recall layer: insert on every turn, and have the agent read before writing.

For feeds that change daily, air-gap your tuning against the latest AI news, browse the repository-owned MCP Directory, and wire scheduled retrieval into your own community workflows.

Summary

The MCP + Weaviate combination gives an agent deterministic hybrid retrieval and graph reasoning without leaving its native client. Define explicit inputSchema, connect via stdio or OAuth-scoped streamable HTTP to Claude Desktop and Cursor, tune the hybrid alpha, then evolve from pure semantic search to cross-reference RAG as your domain grows.

By Deepak Bagada, CEO at SaaSNext & Principal AI Architect.