Qdrant+MCP+connection+refused+Qdrant+not+running+or+wrong+QDRANT

Not specified by the original author.

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

Not specified by the original author.

TL;DR: Qdrant has two ports: 6333 for REST, 6334 for gRPC. The MCP server speaks REST. If QDRANT_URL uses 6334, switch it to 6333.

Connection failed / unexpected response from Qdrant

(With QDRANT_URL set to the service URL for that host and port.)

Fix it

1. Check the port in your client config env block:

{
  "env": {
    "QDRANT_URL": "http://YOUR_QDRANT_HOST:6334"
  }
}

2. Change 6334 to 6333:

{
  "env": {
    "QDRANT_URL": "http://YOUR_QDRANT_HOST:6333"
  }
}

3. Sanity-check with curl:

curl http://YOUR_QDRANT_HOST:6333/collections

Expected: JSON listing collections.

4. Restart the MCP client.

   Expected: the server connects.

When to use this

• QDRANT_URL contains port 6334 and the server cannot talk to Qdrant.
• The curl check against 6333 works but the server is configured for 6334.

When NOT to use this

• The URL already uses 6333 and still fails. Then it is a host, auth, or Qdrant-down problem.
• The error is 401. Auth, not ports.

Compatibility

• qdrant/mcp-server-qdrant and REST-based Qdrant MCP servers.

Why it happens

Qdrant's Docker image publishes both ports side by side, and docs mention them together, so it is easy to grab the wrong one. gRPC speaks HTTP/2 with a binary protocol; a REST client opening a conversation there gets nothing it understands.

Edge cases

• Qdrant Cloud URLs include the port explicitly (:6333). Keep it.
• If you run Qdrant behind a reverse proxy, the external port may differ from 6333. Use whatever port serves the REST API externally.
• Some setups only map 6333 in Docker. Then 6334 is unreachable from outside the container entirely.

Qdrant exposes two ports: 6333 for the REST API and 6334 for gRPC. The qdrant/mcp-server-qdrant and compatible MCP servers communicate over the REST API, so QDRANTURL must use port 6333. The workspace-qdrant-mcp troubleshooting guide shows the canonical REST check as curl YOURHOST/collections and the Docker run mapping both -p 6333:6333 and -p 6334:6334, which is where the confusion originates. Pointing the REST client at the gRPC port produces connection failures. Source: https://github.com/chrisgve/workspace-qdrant-mcp/blob/HEAD/docs/TROUBLESHOOTING.md

Not specified by the original author.

TL;DR: HTTP 401 from Qdrant means the instance requires an API key and the MCP server is not sending one. Set QDRANT_API_KEY in the client config env block next to QDRANT_URL. Qdrant Cloud always needs this.

HTTP 401 Unauthorized

(From the Qdrant instance, surfaced through the MCP server's tools.)

Fix it

1. Confirm the key requirement. Test with curl:

curl -H "api-key value YOUR_KEY" https://your-cluster.qdrant.io:6333/collections

Expected: JSON. Without the header you get 401, proving the key is required.

2. Get the API key: Qdrant Cloud dashboard for cloud clusters, or the value of QDRANT__SERVICE__API_KEY for self-hosted.
3. Set it in the client config:

{
  "mcpServers": {
    "qdrant": {
      "env": {
        "QDRANT_URL": "https://your-cluster.qdrant.io:6333",
        "QDRANT_API_KEY": "your-api-key-here"
      }
    }
  }
}

4. Restart the MCP client.

   Expected: 401 is gone, tools work.

When to use this

• Tools fail with 401 or Unauthorized against Qdrant Cloud or a key-protected self-hosted instance.
• The curl test without the key also 401s.

When NOT to use this

• The error is connection refused. Qdrant is not reachable at all.
• Local Qdrant without a key set. Then no key is needed; check the URL.

Compatibility

• qdrant/mcp-server-qdrant and Qdrant-backed MCP servers that honor QDRANTAPIKEY.
• Qdrant Cloud, self-hosted Qdrant with QDRANTSERVICEAPI_KEY.

Why it happens

Qdrant's API key gate rejects every keyless request with 401. MCP servers that predate key support (or configs copied from keyless local setups) send nothing, so everything 401s. Qdrant Cloud always requires a key, which surprises people moving from local Docker.

Edge cases

• The key travels as the api-key header. It is never logged by well-behaved servers, but do not paste it into chats anyway.
• Sending a key over plain http:// triggers a client warning. Use https:// for key-protected instances.
• If you set the key server-side, the /collections healthcheck also needs it. Use /readyz for unauthenticated health checks.

The code-index-mcp commit feat(qdrant): send QDRANTAPIKEY to server-mode Qdrant (consiliency/code-index-mcp) documents this exact failure: a Qdrant server started with QDRANTSERVICEAPIKEY rejects every request without the key, and the MCP server had no way to send one, so server mode got HTTP 401. The fix was reading QDRANTAPIKEY and passing it to every URL-mode QdrantClient, with a 401/403 suggesting the user set QDRANTAPIKEY. The workspace-qdrant-mcp troubleshooting guide documents the same: Unauthorized or 403 Forbidden with Qdrant Cloud, fixed by setting QDRANTAPI_KEY. Sources: https://github.com/consiliency/code-index-mcp/commit/bf7782377596002ba7f342b8f0c39e10bd0e0de0 and https://github.com/chrisgve/workspace-qdrant-mcp/blob/HEAD/docs/TROUBLESHOOTING.md