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)

[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)

{
  "mcpServers": {
    "epanet": {
      "httpUrl": "https://<space>.hf.space/mcp",
      "headers": { "Authorization": "Bearer <YOUR_KEY>" },
      "timeout": 30000
    }
  }
}

Or one-liner:

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)

{
  "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."