Weaviate MCP: wrong connection mode for Cloud vs local Docker

TL;DR: Weaviate has two connection modes and they are not interchangeable. Weaviate Cloud needs the cloud connection (URL plus API key); local Docker needs the plain local connection. If your MCP server is configured for one but pointed at the other, fix the config to match the deployment.

Connection failed: unexpected response / authentication handshake failure

(Exact text varies; the signature is a local-style config pointed at Cloud, or vice versa.)

Fix it

1. Identify your deployment:

   • URL like https://xxx.weaviate.cloud = Weaviate Cloud. Needs WEAVIATE_API_KEY.
   • URL like the service URL for that host and port = local Docker. Usually no key.
2. Align the MCP server config:

{
  "env": {
    "WEAVIATE_URL": "https://your-cluster.weaviate.cloud",
    "WEAVIATE_API_KEY": "your-key"
  }
}

For local:

{
  "env": {
    "WEAVIATE_URL": "YOUR_HOST"
  }
}

3. Restart the MCP client.

   Expected: the server connects under the correct mode.

When to use this

• You switched between local Docker and Weaviate Cloud and the server broke.
• The config has a Cloud URL but no API key, or a local URL with a key that does nothing.

When NOT to use this

• 401 with the key set. The key is wrong, not the mode.
• Connection refused on YOUR_HOST. Weaviate Docker is not running.

Compatibility

• weaviate/mcp-server-weaviate.
• Weaviate Cloud and self-hosted Docker.

Why it happens

The Weaviate client library has separate connection paths with different TLS, auth, and port assumptions. MCP servers wrap one of them based on config. A Cloud URL with local-mode config (or the reverse) fails the handshake because each side expects the other's protocol.

Edge cases

• Weaviate Cloud also uses gRPC on port 50051 for some operations. If REST works but queries hang, the gRPC port may be blocked. That is a separate firewall issue.
• Self-hosted Weaviate with auth enabled behaves like Cloud. Treat it as the Cloud mode.
• Double-check for a trailing slash or path in WEAVIATE_URL. The base URL only.

The weaviate-cloud secure coding rules (tikitribe/claude-secure-coding-rules rules/rag/vector-managed/weaviate-cloud/CLAUDE.md) show the two distinct connection patterns: weaviate.connecttoweaviatecloud for Cloud clusters (with clusterurl and AuthApiKey) versus a local connection for Docker instances (WEAVIATEURL=YOURHOST). Using the cloud helper against a local instance or the local pattern against Cloud fails. MCP server configs must match the deployment type. Source: https://github.com/tikitribe/claude-secure-coding-rules/blob/HEAD/rules/rag/vector-managed/weaviate-cloud/CLAUDE.md