Weaviate MCP: wrong connection mode for Cloud vs local Docker

Not specified by the original author.

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

Not specified by the original author.

TL;DR: Weaviate Cloud requires an API key and your MCP server is not sending one. Set WEAVIATE_API_KEY in the server's environment alongside WEAVIATE_URL. Local Docker Weaviate does not need this, which is why the same config breaks when you move to Cloud.

401 Unauthorized

(From Weaviate Cloud, surfaced through the MCP server's tools.)

Fix it

1. In the Weaviate Cloud dashboard, create an API key for your cluster. Copy it.
2. Set both variables in the MCP client config env block:

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

3. Restart the MCP client.

   Expected: 401 is gone, collection tools work.

When to use this

• Tools fail with 401 against a *.weaviate.cloud URL.
• The same config works against local Docker Weaviate.

When NOT to use this

• Local Docker Weaviate with auth disabled. No key is needed; check the URL.
• Connection refused or timeout. The instance is unreachable.

Compatibility

• weaviate/mcp-server-weaviate and Weaviate-backed MCP servers.
• Weaviate Cloud.

Why it happens

Weaviate Cloud mandates API key auth on every request. Local Docker images ship with auth off for convenience. Configs migrate from local to Cloud carrying only the URL, and the missing key produces a bare 401 with no hint about what to set.

Edge cases

• The Cloud URL is https://. Plain http:// fails differently.
• API keys are per-cluster. A key for cluster A does not work on cluster B.
• If you enabled auth on self-hosted Weaviate (APIKEY auth), the same variable applies. Check how your server maps it.

The weaviate-cloud secure coding rules (tikitribe/claude-secure-coding-rules rules/rag/vector-managed/weaviate-cloud/CLAUDE.md) show the correct Weaviate Cloud connection pattern: weaviate.connecttoweaviatecloud with clusterurl from WEAVIATEURL and authcredentials=AuthApiKey from WEAVIATEAPIKEY. Weaviate Cloud requires API key authentication; without the key the server gets 401 Unauthorized. Local Docker Weaviate typically runs without auth, which is why configs copied from local setups break against Cloud. Source: https://github.com/tikitribe/claude-secure-coding-rules/blob/HEAD/rules/rag/vector-managed/weaviate-cloud/CLAUDE.md

Not specified by the original author.

TL;DR: Weaviate does vectors over gRPC on port 50051, and your Docker run probably only published 8080. REST calls work, queries hang. Add -p 50051:50051 to the container and restart it.

Query hangs / gRPC connection timeout to weaviate:50051

Fix it

1. Check how Weaviate was started:

docker ps --format "{{.Names}} {{.Ports}}" | grep weaviate

If you see only 8080->8080 and no 50051, that is the bug.

2. Recreate the container with both ports:

docker run -d --name weaviate -p 8080:8080 -p 50051:50051 semitechnologies/weaviate:latest

In Docker Compose, add "50051:50051" under ports.

3. Restart the MCP client so it reconnects.

   Expected: queries complete instead of hanging.

When to use this

• REST calls to Weaviate (schema, health) work but vector queries hang or time out.
• Weaviate runs in Docker with only 8080 published.

When NOT to use this

• Everything fails including REST. Then Weaviate is down or the URL is wrong.
• Weaviate Cloud. Cloud exposes gRPC itself; this is a self-hosted Docker issue.

Compatibility

• weaviate/mcp-server-weaviate against self-hosted Docker Weaviate.

Why it happens

Weaviate moved its hot paths to gRPC for performance, but quickstart Docker commands historically published only the REST port. The MCP server's simple calls succeed over REST, masking the problem until a real vector query needs gRPC and blocks.

Edge cases

• Firewalls between the MCP host and the Weaviate host must allow 50051 too, not just 8080.
• Some clients fall back to REST for queries. Slower, but a workaround if you cannot open the port.
• In Kubernetes, expose 50051 on the Service, not just 8080.

Weaviate's architecture splits traffic: REST on 8080 and gRPC on 50051, with the high-performance query paths using gRPC. Docker run examples for local Weaviate commonly map only -p 8080:8080, leaving gRPC unreachable from outside the container. Clients that need gRPC then hang or fail while plain REST calls succeed. The fix is adding -p 50051:50051 to the Docker run or compose ports. This is a well-known Weaviate Docker gotcha.