olyannaa · olyannaa · Jul 1, 2026 · Jul 1, 2026
diff --git a/.railwayignore b/.railwayignore
@@ -0,0 +1,17 @@
+.git
+.mypy_cache
+.pytest_cache
+.qdrant_db
+.ruff_cache
+**/__pycache__/
+**/*.pyc
+.DS_Store
+
+data/
+eval/
+htmlcov/
+.coverage
+
+.env
+.env.*
+!.env.example
diff --git a/README.en.md b/README.en.md
@@ -39,7 +39,7 @@ source of production recommendations.
 - [Quick start](#quick-start)
 - [Single-query advisor](#single-query-advisor)
 - [Workload analyzer](#workload-analyzer)
-- [MCP deployment](#mcp-deployment)
+- [MCP](#mcp)
 - [Data Science and ML](#data-science-and-ml)
 - [Evaluation](#evaluation)
 - [Security](#security)
@@ -175,47 +175,64 @@ Normalized SQL: select * from events final where message like ?
 
 More details: [docs/workload.md](docs/workload.md).
 
-## MCP deployment
+## MCP
 
 Local stdio MCP for Claude Desktop, Cursor, Zed, and other MCP clients:
 
 ```bash
 poetry run chadvisor mcp-server
 ```
 
-Streamable HTTP MCP endpoint for remote-compatible demos:
+Public MCP endpoint for testing without a local install:
 
-```bash
-poetry run chadvisor mcp-http-server \
-  --host 127.0.0.1 \
-  --port 8765 \
-  --path /mcp
+```text
+https://clickadvisor-mcp-production.up.railway.app/mcp
 ```
 
-Endpoint:
+Claude / Anthropic API can connect to the remote MCP server as a URL-based
+server:
 
 ```text
-http://127.0.0.1:8765/mcp
+Claude / Claude Desktop:
+Customize -> Connectors -> Add custom connector
+Name: ClickAdvisor
+URL:  https://clickadvisor-mcp-production.up.railway.app/mcp
 ```
 
-For a defense/demo, the server can run as a remote endpoint behind HTTPS/auth:
-VPS + reverse proxy, Railway/Render/Fly.io, Cloudflare Tunnel, or Tailscale.
-A public unauthenticated MCP endpoint is not recommended because SQL and query
-context are sensitive.
+Claude Code:
 
-Fastest path to a public link:
+```bash
+claude mcp add --transport http clickadvisor \
+  https://clickadvisor-mcp-production.up.railway.app/mcp
+```
 
-1. push the repository to GitHub;
-2. create a Railway project from the GitHub repo or a Render Blueprint;
-3. let the platform build the root `Dockerfile`;
-4. generate/open the public domain;
-5. share an endpoint like:
+Anthropic API:
 
-```text
-https://<your-service>.up.railway.app/mcp
-https://<your-service>.onrender.com/mcp
+```json
+{
+  "mcp_servers": [
+    {
+      "type": "url",
+      "name": "clickadvisor",
+      "url": "https://clickadvisor-mcp-production.up.railway.app/mcp"
+    }
+  ]
+}
 ```
 
+Available MCP tools:
+
+| Tool | Purpose |
+|---|---|
+| `analyze_query` | Markdown report for ClickHouse SQL |
+| `analyze_query_json` | Structured JSON for automation |
+| `list_rules` | Registered rule catalog |
+| `detect_ch_version` | ClickHouse version detection through HTTP API |
+
+If you open `/mcp` in a browser, you may see `Not Acceptable: Client must
+accept text/event-stream`. That is expected: the endpoint is for MCP clients,
+not a regular HTML page.
+
 More details:
 
 - [docs/MCP.md](docs/MCP.md)

diff --git a/README.md b/README.md
@@ -39,7 +39,7 @@ confidence, объяснение и rewrite-пример там, где rewrite
 - [Быстрый старт](#быстрый-старт)
 - [Single-query advisor](#single-query-advisor)
 - [Workload analyzer](#workload-analyzer)
-- [MCP deployment](#mcp-deployment)
+- [MCP](#mcp)
 - [Data Science и ML](#data-science-и-ml)
 - [Evaluation](#evaluation)
 - [Security](#security)
@@ -175,47 +175,63 @@ Normalized SQL: select * from events final where message like ?
 
 Подробнее: [docs/workload.md](docs/workload.md).
 
-## MCP Deployment
+## MCP
 
 Локальный stdio MCP для Claude Desktop, Cursor, Zed и других MCP-клиентов:
 
 ```bash
 poetry run chadvisor mcp-server
 ```
 
-Streamable HTTP MCP endpoint для remote-compatible demo:
+Публичный MCP endpoint для проверки без локальной установки:
 
-```bash
-poetry run chadvisor mcp-http-server \
-  --host 127.0.0.1 \
-  --port 8765 \
-  --path /mcp
+```text
+https://clickadvisor-mcp-production.up.railway.app/mcp
 ```
 
-Endpoint:
+В Claude / Anthropic API remote MCP подключается как URL-based server:
 
 ```text
-http://127.0.0.1:8765/mcp
+Claude / Claude Desktop:
+Customize -> Connectors -> Add custom connector
+Name: ClickAdvisor
+URL:  https://clickadvisor-mcp-production.up.railway.app/mcp
 ```
 
-Для защиты можно поднять удалённый demo endpoint behind HTTPS/auth proxy:
-VPS + reverse proxy, Railway/Render/Fly.io, Cloudflare Tunnel или Tailscale.
-Публичный unauthenticated MCP endpoint не рекомендуется: SQL и query context
-считаются чувствительными.
+Claude Code:
 
-Самый быстрый путь получить публичную ссылку:
+```bash
+claude mcp add --transport http clickadvisor \
+  https://clickadvisor-mcp-production.up.railway.app/mcp
+```
 
-1. push репозитория в GitHub;
-2. создать Railway project from GitHub repo или Render Blueprint;
-3. платформа соберёт root `Dockerfile`;
-4. открыть public domain;
-5. передать экспертам URL вида:
+Anthropic API:
 
-```text
-https://<your-service>.up.railway.app/mcp
-https://<your-service>.onrender.com/mcp
+```json
+{
+  "mcp_servers": [
+    {
+      "type": "url",
+      "name": "clickadvisor",
+      "url": "https://clickadvisor-mcp-production.up.railway.app/mcp"
+    }
+  ]
+}
 ```
 
+Доступные MCP tools:
+
+| Tool | Назначение |
+|---|---|
+| `analyze_query` | Markdown-отчёт по ClickHouse SQL |
+| `analyze_query_json` | Структурированный JSON для автоматизации |
+| `list_rules` | Список зарегистрированных правил |
+| `detect_ch_version` | Определение версии ClickHouse через HTTP API |
+
+Если открыть `/mcp` в браузере, можно увидеть ошибку `Not Acceptable: Client
+must accept text/event-stream`. Это нормально: endpoint предназначен для MCP
+clients, а не для обычной HTML-страницы.
+
 Подробнее:
 
 - [docs/MCP.md](docs/MCP.md)

diff --git a/docs/MCP.md b/docs/MCP.md
@@ -35,6 +35,50 @@ http://127.0.0.1:8765/mcp
 For a remote demo, expose this endpoint only through HTTPS and authentication.
 See [MCP Deployment Options](mcp-deployment.md).
 
+## Connect To Public Remote MCP
+
+Remote MCP clients connect to ClickAdvisor through the hosted Streamable HTTP
+endpoint:
+
+```text
+https://clickadvisor-mcp-production.up.railway.app/mcp
+```
+
+Claude / Anthropic API URL-based server config:
+
+Claude / Claude Desktop:
+
+```text
+Customize -> Connectors -> Add custom connector
+Name: ClickAdvisor
+URL:  https://clickadvisor-mcp-production.up.railway.app/mcp
+```
+
+Claude Code:
+
+```bash
+claude mcp add --transport http clickadvisor \
+  https://clickadvisor-mcp-production.up.railway.app/mcp
+```
+
+Anthropic API:
+
+```json
+{
+  "mcp_servers": [
+    {
+      "type": "url",
+      "name": "clickadvisor",
+      "url": "https://clickadvisor-mcp-production.up.railway.app/mcp"
+    }
+  ]
+}
+```
+
+Opening the endpoint in a browser can return `Not Acceptable: Client must
+accept text/event-stream`. This is expected for Streamable HTTP MCP; use an MCP
+client or MCP Inspector to test the tool calls.
+
 ## Connect to Claude Desktop
 
 Add this to `~/Library/Application Support/Claude/claude_desktop_config.json`:

diff --git a/docs/mcp-deployment.md b/docs/mcp-deployment.md
@@ -112,15 +112,15 @@ the defense".
 1. Push this repository to GitHub.
 2. Open Railway and create a new project from the GitHub repository.
 3. Railway reads `railway.json` and builds the root `Dockerfile`.
-4. In service variables, keep:
+4. The Docker command reads Railway's injected `PORT` value and starts the MCP
+   server on that port.
+5. Generate a public domain for the service. If using the CLI and Railway
+   reports the app listening on `8080`, use:
 
-```text
-PORT=8000
-MCP_PATH=/mcp
+```bash
+railway domain -p 8080
 ```
 
-5. Open the service settings and generate a public domain.
-
 Result:
 
 ```text