Weaviate MCP Server Cursor IDE Setup (2026): MCP_SERVER_ENABLED, Bearer Auth & Hybrid Search

How do you connect Weaviate to Cursor? Set MCP_SERVER_ENABLED=true on your Weaviate instance (v1.37 and later — it's built into the weaviate/weaviate server binary, not a separate package you install), then add a weaviate entry to ~/.cursor/mcp.json pointing at http://localhost:8080/v1/mcp (or your cluster's URL) with your API key passed as a bearer token in headers. Restart Cursor, and it can inspect your collection schemas, list tenants, and run hybrid vector+keyword search over your data — all read-only by default, with a second env var required to enable writes.

That's the detail every other MCP setup guide on this site doesn't have to deal with: there's no npx package, no uvx command, nothing to pip install. Weaviate shipped its MCP server as a feature flag inside the database itself, so "installing" it means flipping a config value on a Weaviate instance you already run, not adding a new process to mcp.json's command field. If you're coming from the Qdrant guide or Pinecone guide expecting a similar command/args block, this one only needs a url and headers — closer to how Context7's remote server is configured than to either of those.

What the Weaviate MCP Server Can Do

The server exposes four tools, and which ones are active depends on a single environment variable:

Typical prompts once connected:

Prerequisites

Step 1: Enable the Server on Weaviate

The server ships disabled by default. In your docker-compose.yml (or equivalent config for a managed cluster), set:

services:
  weaviate:
    image: cr.weaviate.io/semitechnologies/weaviate:1.38.0
    environment:
      MCP_SERVER_ENABLED: 'true'
      MCP_SERVER_WRITE_ACCESS_ENABLED: 'false'
      AUTHENTICATION_APIKEY_ENABLED: 'true'
      AUTHENTICATION_APIKEY_ALLOWED_KEYS: 'your-api-key-here'
      AUTHENTICATION_APIKEY_USERS: 'cursor-mcp@yourteam.com'
    ports:
      - "8080:8080"

Three environment variables control the server:

Leave write access off unless you specifically want an agent inserting or modifying data. For most Cursor workflows — an agent reading your product catalog or support ticket collection to answer questions — the read-only default is the right call, and it means a prompt-injection attempt or a bad agent decision can't silently mutate your data.

If you're running Weaviate Cloud instead of self-hosting, the MCP server may be enabled per-cluster through the cloud console rather than an env var you set yourself — check your cluster's settings page, since the docker-compose flags above only apply to self-managed deployments.

Step 2: Configure RBAC Permissions (If RBAC Is On)

If your instance has role-based access control enabled, the API key's role needs explicit MCP permissions — having general read/write access to a collection isn't enough on its own:

Without read_mcp granted, every MCP tool call fails with an authorization error even though MCP_SERVER_ENABLED=true and the endpoint responds — this trips people up because the server itself looks healthy; it's the specific role grant that's missing. Add the permission through your existing RBAC role management (Weaviate's admin API or console), not through anything in mcp.json.

If you're not using RBAC and are relying on the simpler API-key auth shown in Step 1, skip this — anyone with a valid API key gets whatever the server's default read/write gating allows.

Step 3: Configure Cursor

Add this to ~/.cursor/mcp.json (or your project's .cursor/mcp.json for a project-scoped connection):

{
  "mcpServers": {
    "weaviate": {
      "url": "http://localhost:8080/v1/mcp",
      "headers": {
        "Authorization": "Bearer your-api-key-here"
      }
    }
  }
}

For a remote or Weaviate Cloud instance, swap in your cluster's hostname:

{
  "mcpServers": {
    "weaviate": {
      "url": "https://your-cluster-id.weaviate.network/v1/mcp",
      "headers": {
        "Authorization": "Bearer your-api-key-here"
      }
    }
  }
}

If anonymous access is enabled on the instance (common for local dev, rare and inadvisable in production), you can drop the headers block entirely:

{
  "mcpServers": {
    "weaviate": {
      "url": "http://localhost:8080/v1/mcp"
    }
  }
}

There's no command, no args, no env block for a local process — this is a plain remote HTTP connection, the same shape Cursor uses for Context7's hosted server. Restart Cursor after saving mcp.json.

Step 4: Test the Connection

Start with a schema check, since it doesn't touch data and confirms the connection and auth are both working:

What properties does the [YourCollectionName] collection have in Weaviate?

If that returns real schema details, follow with a search:

Search my [YourCollectionName] collection for anything related to [a topic you know exists in the data]

A working weaviate-query-hybrid call returns results scored on both vector similarity and BM25 keyword relevance — you'll typically see it surface a document that matches your wording exactly alongside one that's only semantically related, which is the combination the tool is built for.

Gotchas Worth Knowing Before You Debug for an Hour

Version check first, always. Because this feature is version-gated rather than a package with its own changelog you'd naturally check, it's easy to spend time debugging a 404 on /v1/mcp that's actually just an out-of-date Weaviate instance. Confirm the version before touching mcp.json.

MCP_SERVER_CONFIG_PATH doesn't hot-reload. If you're customizing tool descriptions through this file, changes require a full Weaviate restart to take effect — editing the file while the container keeps running does nothing.

Write access is instance-wide, not per-key. Unlike RBAC's per-role granularity, MCP_SERVER_WRITE_ACCESS_ENABLED is a single on/off switch for the whole server. You can't have one API key with write access and another read-only through this variable alone — that separation has to come from RBAC's create_mcp/update_mcp grants layered on top.

Prometheus metrics are on by default if metrics are already enabled. The server emits six weaviate_mcp_*-prefixed metrics on your existing metrics endpoint (call counts and latencies per tool, roughly). If you're already scraping Weaviate with Prometheus, you get MCP usage visibility for free — worth checking before building your own logging around agent tool calls.

Troubleshooting

404 on /v1/mcp
Your Weaviate version predates the MCP server, or MCP_SERVER_ENABLED isn't actually set to true on the running instance (not just in a config file that hasn't been applied yet). Confirm both — a stale container running an old image is the most common cause here, especially if you edited docker-compose.yml but didn't rebuild/restart.

"Unauthorized" despite a correct API key
If RBAC is enabled, the key's role is missing read_mcp (or create_mcp/update_mcp for write calls). A valid API key with general collection access still fails MCP calls without this specific grant — check the role's permissions, not just whether the key itself is valid.

weaviate-objects-upsert doesn't show up as an available tool
MCP_SERVER_WRITE_ACCESS_ENABLED is false (the default). Cursor only sees the tools the server actually advertises — there's no upsert tool to call until that flag is flipped on the instance.

Connects fine locally, fails from a teammate's machine
http://localhost:8080 only resolves on the machine actually running Weaviate. Anyone else needs the real hostname or IP the instance is reachable at, plus confirmation that whatever's between them and the container — a firewall, a Docker network boundary, a VPN — isn't blocking port 8080.

Hybrid search returns only keyword-style matches, nothing semantic
This usually means the collection's vectorizer isn't configured, or objects were inserted without vectors (e.g., through a bulk import that skipped embedding). weaviate-query-hybrid can only weight the vector side of the search if vectors actually exist for the objects being searched — this is a data problem, not an MCP config problem.

When Not to Use This

If you need full collection administration — creating collections, changing vectorizer configuration, deleting data outside of upsert, managing backups — this MCP server doesn't cover it, by design. It's scoped to schema inspection, tenant listing, hybrid search, and (optionally) upserts. For anything else, you're still using Weaviate's own client SDKs, the Weaviate Cloud console, or weaviate-cli directly. Think of the MCP server as giving an agent read access (and narrowly scoped write access) to data that already exists in a collection you set up some other way — not a replacement for your existing Weaviate tooling.

It's also not the right choice if you want an agent to freely create new collections on the fly based on conversation — there's no collections-create tool exposed here, intentionally; schema changes stay a deliberate, human-initiated action.

Frequently Asked Questions

Q: Do I need to install a separate MCP server package for Weaviate?
A: No. Unlike Qdrant (uvx mcp-server-qdrant) or many other MCP integrations, Weaviate's MCP server is built directly into the weaviate/weaviate server binary starting from v1.37.1. There's nothing to npx, uvx, or pip install — you enable it with an environment variable on the Weaviate instance itself.

Q: What Weaviate version do I need?
A: v1.37.1 or later, where it shipped as a preview feature; treat v1.38 and later as the stable baseline. Check your running instance's version before debugging a 404 on /v1/mcp — an out-of-date instance is the most common reason the endpoint doesn't respond.

Q: Can Cursor write data into Weaviate through this, or is it read-only?
A: Read-only by default. Setting MCP_SERVER_WRITE_ACCESS_ENABLED=true on the Weaviate instance exposes the weaviate-objects-upsert tool for batch insert/update; without it, only the three read tools (weaviate-collections-get-config, weaviate-tenants-list, weaviate-query-hybrid) are available.

Q: Why does authentication fail even though my API key is correct?
A: If RBAC is enabled on your instance, having a valid API key isn't sufficient — its role also needs read_mcp permission for read tools, and create_mcp/update_mcp for the write tool. This is a separate grant from general collection read/write access, and it's the detail people miss most often.

Q: How is this different from the Qdrant or Pinecone MCP servers?
A: Structurally, not just by vendor. Qdrant's and Pinecone's servers are separate processes you run alongside your editor (uvx mcp-server-qdrant, an npx package respectively), configured with command/args/env in mcp.json. Weaviate's is a feature flag inside the database server itself, reached over plain HTTP with a url and headers block — closer in shape to a hosted remote server like Context7 than to either vector-DB competitor's approach. See the Qdrant setup guide or Pinecone setup guide for the comparison.

Q: Does hybrid search require any extra configuration beyond enabling the MCP server?
A: The weaviate-query-hybrid tool itself needs no extra setup, but it can only combine vector and keyword scoring if the collection actually has vectors — a collection with an unconfigured vectorizer or objects inserted without embeddings will effectively behave like keyword-only search regardless of what the tool tries to do.

Related Guides