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.

```text
Query hangs / gRPC connection timeout to weaviate:50051
```

## Fix it

1. Check how Weaviate was started:

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

```bash
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.