Qdrant MCP: connection refused (Qdrant not running or wrong QDRANT_URL)

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.

Connection refused

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

Fix it

1. Check whether Qdrant is actually up:

curl http://YOUR_QDRANT_HOST:6333/collections

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

2. Start it:

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.

The workspace-qdrant-mcp troubleshooting guide (chrisgve/workspace-qdrant-mcp docs/TROUBLESHOOTING.md) documents this exact problem: Connection refused when attempting to connect to Qdrant, with diagnosis via curl YOURHOST/collections (expected: JSON response with collections list; if refused: Qdrant is not running) and the fix of starting the Qdrant container with docker run -p 6333:6333 -p 6334:6334 qdrant/qdrant, plus verifying QDRANTURL. The official qdrant/mcp-server-qdrant uses the same QDRANT_URL variable. Source: https://github.com/chrisgve/workspace-qdrant-mcp/blob/HEAD/docs/TROUBLESHOOTING.md