CLIENTS.md

# Connecting clients

Base URL: `https://<owner>-<space-name>.hf.space`
(shown on the Space page once it's running — e.g. `https://razaali10-epanet-mcp-server.hf.space`)

Two endpoints:
- **Streamable HTTP** → `…/mcp`  (preferred by all five clients below)
- **SSE** → `…/sse`  (legacy fallback; Claude Desktop via `mcp-remote`)

If you set the `CLIENT_API_KEY` Space secret, every client must send
`Authorization: Bearer <key>` (or `X-API-Key: <key>`).

| Client | Transport | Static API-key header? | Notes |
|--------|-----------|------------------------|-------|
| HuggingChat | Streamable HTTP | ✅ | Add under Settings → add MCP server |
| Codex | Streamable HTTP | ✅ | `http_headers` in `config.toml` |
| Perplexity | Streamable HTTP | ✅ (API Key / header) | Pro/Max/Enterprise only |
| Gemini CLI | Streamable HTTP | ✅ | `httpUrl` + `headers` in `settings.json` |
| ChatGPT | Streamable HTTP | ❌ (OAuth/None only) | **Run the Space with no key**, select "No authentication" |

> ⚠️ **ChatGPT** cannot send a static API key. To use it, leave `CLIENT_API_KEY`
> unset (open mode). If you need the key on for the other four, that's fine —
> just skip ChatGPT, or run a second open instance for it.

---

## HuggingChat (HF ChatUI)
Settings → Tools / MCP → add server:
- **URL**: `https://<space>.hf.space/mcp`
- **Header**: `Authorization: Bearer <YOUR_KEY>`

## Codex (`~/.codex/config.toml`)
```toml
[mcp_servers.epanet]
url = "https://<space>.hf.space/mcp"
http_headers = { Authorization = "Bearer <YOUR_KEY>" }
```

## Perplexity (Pro / Max / Enterprise)
Account settings → Connectors → **+ Custom connector → Remote**:
- **MCP Server URL**: `https://<space>.hf.space/mcp`
- **Transport**: Streamable HTTP
- **Authentication**: API Key → send as header `X-API-Key: <YOUR_KEY>`
  (or `Authorization: Bearer <YOUR_KEY>`)

## Gemini CLI (`~/.gemini/settings.json`)
```json
{
  "mcpServers": {
    "epanet": {
      "httpUrl": "https://<space>.hf.space/mcp",
      "headers": { "Authorization": "Bearer <YOUR_KEY>" },
      "timeout": 30000
    }
  }
}
```
Or one-liner:
```bash
gemini mcp add --transport http \
  --header "Authorization: Bearer <YOUR_KEY>" \
  epanet https://<space>.hf.space/mcp
```

## ChatGPT (Developer Mode — Plus/Pro/Business/Enterprise/Edu)
Requires the Space in **open mode** (no `CLIENT_API_KEY`).
Settings → Apps/Connectors → Advanced → **Developer mode** → Create app:
- **URL**: `https://<space>.hf.space/mcp`
- **Transport**: Streamable HTTP
- **Authentication**: No authentication

## Claude Desktop (SSE via mcp-remote)
```json
{
  "mcpServers": {
    "epanet": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://<space>.hf.space/sse",
               "--header", "Authorization: Bearer <YOUR_KEY>"]
    }
  }
}
```

---

## First things to try
1. "List the bundled networks."
2. "Load net3.inp from /home/user/app/networks/ and summarise it."
3. "Run a hydraulic simulation on net3 and tell me the lowest-pressure node at hour 12."
4. "Simulate a 20% burst on a pipe in net3 and compare pressures to baseline."