Qdrant MCP: QDRANT_URL on gRPC port 6334 (use REST port 6333)

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

Strip :6333 from the host before passing it in, e.g. host = host.replace(":6333", "", 1) if ":6333" in host else host, and the connection goes through. The reporter confirmed removing the port from the URL fixed it.

Steps

1. Reporter-verified workaround: the host URL with the default Qdrant port breaks the internal client. Strip :6333 from the host before passing it in, e.g. host = host.replace(":6333", "", 1) if ":6333" in host else host, and the connection goes through. The reporter confirmed removing the port from the URL fixed it. So if your remote Qdrant URL includes the port, drop it from the string you hand mem0; the client appends what it needs itself.

When to use

You are seeing this: Pointing mem0 at a remote Qdrant instance via the url parameter throws a connection exception. Use this skill when you run into "Remote Qdrant fails to connect when the URL includes port 6333".

When not to use

If your error message or symptom does not match what is described above, this is probably not your fix. Search for your exact error text instead of forcing this one to fit.

Versions

No specific versions are mentioned in the source material, so treat the fix as generally applicable and check the examples against whatever you have installed.

Why this happens

The original report does not dig into a root cause. It documents the symptom and the fix that resolved it.

In gh:mem0ai/mem0#3092 (https://github.com/mem0ai/mem0/issues/3092), the reporter ran into this: Pointing mem0 at a remote Qdrant instance via the url parameter throws a connection exception. The config looks right, host and port included, but the Qdrant client inside mem0 never connects. The reporter was using an Ollama-backed setup with Qdrant as the vector store and could not get past the connection step. The verified resolution: Reporter-verified workaround: the host URL with the default Qdrant port breaks the internal client. Strip :6333 from the host before passing it in, e.g. host = host.replace(":6333", "", 1) if ":6333" in host else host, and the connection goes through. The reporter confirmed removing the port from the URL fixed it. So if your remote Qdrant URL includes the port, drop it from the string you hand mem0; the client appends what it needs itself.