TL;DR: `Connection refused` means ChromaDB is not running where the MCP server is looking. Start ChromaDB, confirm `CHROMA_HOST` and `CHROMA_PORT` match, restart the client.

```text
Connection refused
```

(When the Chroma MCP server dials the ChromaDB instance.)

## Fix it

1. Start ChromaDB if it is not running:

```bash
chroma run --path ./chroma_db
```

   Or with Docker:

```bash
docker run -d -p 8000:8000 chromadb/chroma
```

2. Verify it answers:

```bash
curl http://YOUR_CHROMA_HOST:8000/api/v2/heartbeat
```

   Expected: a JSON heartbeat response.

3. Match the MCP server config to it:

```json
{
  "env": {
    "CHROMA_CLIENT_TYPE": "http",
    "CHROMA_HOST": "YOUR_CHROMA_HOST",
    "CHROMA_PORT": "8000"
  }
}
```

4. Restart the MCP client.

   Expected: the server connects and collection tools work.

## When to use this

- The MCP server fails with connection refused mentioning the Chroma host/port.
- The heartbeat curl also fails (proves ChromaDB is down, not the MCP server).

## When NOT to use this

- The heartbeat works but the MCP server still fails. Then the host/port in the client config is wrong.
- Collection not found errors. ChromaDB is up; the collection name is wrong.

## Compatibility

- chroma-mcp in http client mode, rkilchmn/chroma-mcp-server.
- ChromaDB local (`chroma run`) and Docker.

## Why it happens

The MCP server is a client of ChromaDB, not a bundle of it. Fresh setups configure the MCP side but never start the database, or start it on a different port. The default port 8000 is a convention, not a guarantee.

## Edge cases

- In Docker, the MCP server needs the container or service name as host, not YOUR_HOST.
- `chroma run` defaults to port 8000. If something else holds 8000, ChromaDB fails to start. Check with `lsof -i :8000`.
- For embedded/persistent mode, the server uses a data directory instead of host/port. Do not mix the two modes.