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.

1. 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"
  }
}

1. 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.