Weaviate MCP: queries hang, gRPC port 50051 not published in Docker

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.