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.

```text
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:

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

   For local:

```json
{
  "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.