TL;DR: `Connection refused` means Qdrant is not running where the MCP server is looking. Start Qdrant, confirm `curl [QDRANT_URL]/collections` returns JSON, and make sure `QDRANT_URL` in the client config matches. Then restart the client.

```text
Connection refused
```

(When the Qdrant MCP server tries to reach the Qdrant instance.)

## Fix it

1. Check whether Qdrant is actually up:

```bash
curl http://YOUR_QDRANT_HOST:6333/collections
```

   Expected: a JSON response listing collections. If it refuses, Qdrant is not running.

2. Start it:

```bash
docker run -d --name qdrant -p 6333:6333 -p 6334:6334 qdrant/qdrant
```

3. Verify `QDRANT_URL` in the MCP client config `env` block matches where Qdrant listens. Default is the service URL for that host and port. For Docker setups, use the container or service name, not YOUR_HOST.

4. Restart the MCP client.

   Expected: the server connects and search/store tools work.

## When to use this

- The MCP server fails with connection refused mentioning the Qdrant address.
- The curl check in step 1 also refuses (proves Qdrant is down, not the MCP server).

## When NOT to use this

- The curl check works but the MCP server still fails. Then the URL in the client config is wrong.
- The error is 401 or Unauthorized. Qdrant is up; the API key is missing.

## Compatibility

- qdrant/mcp-server-qdrant and other Qdrant MCP servers using QDRANT_URL.
- Qdrant self-hosted (Docker) and Qdrant Cloud.

## Why it happens

The MCP server is a thin client over Qdrant's REST API. It does not bundle Qdrant, so a fresh machine has the MCP server configured but nothing listening on 6333. The default URL assumes local Qdrant, which breaks in Docker and remote setups.

## Edge cases

- Port 6333 is the REST API; 6334 is gRPC. The MCP server needs the REST port in QDRANT_URL.
- Qdrant Cloud URLs are the service URL for that host and port and need the API key too.
- If Qdrant starts but the first request is slow, give it a few seconds. Cold starts on small machines take a moment.