From 885fe28a6717723fb6ec1c4821cb10e42215c6ed Mon Sep 17 00:00:00 2001 From: Jayme Klein Date: Mon, 20 Jul 2026 14:06:17 -0300 Subject: [PATCH] docs: correct MCP transport (SSE to streamable HTTP) and Claude Desktop config path The MCP server runs stateless streamable HTTP (api/services/mcp/server.py), but the README still described it as SSE in three places, contradicting its own MCP section and the code. This fixes the Features bullet, the architecture diagram, and the ports table. It also corrects the Claude Desktop config path to the macOS location (Library/Application Support/Claude) with an explicit macOS/Windows split, and updates two stale SSE comments in api/main.py and api/routers/mcp.py so the code matches the transport it mounts. --- README.md | 10 +++++----- api/main.py | 2 +- api/routers/mcp.py | 2 +- 3 files changed, 7 insertions(+), 7 deletions(-) diff --git a/README.md b/README.md index adff5e9..88ae9fa 100644 --- a/README.md +++ b/README.md @@ -30,7 +30,7 @@ ## Features - **Hybrid search** — semantic (pgvector) fused with BM25 keyword ranking (ParadeDB `pg_search`) in a single SQL round-trip. -- **Two APIs** — a REST API (`/docs` for OpenAPI) and an MCP server over SSE for Claude Desktop, Cursor, and Zed. +- **Two APIs** — a REST API (`/docs` for OpenAPI) and an MCP server over streamable HTTP for Claude Desktop, Cursor, and Zed. - **Pluggable embeddings** — Ollama, sentence-transformers, any OpenAI-compatible endpoint, or Google Gemini. - **Pluggable storage** — uploaded files live on local disk by default, or on any number of S3-compatible backends (self-hosted MinIO, AWS S3, …). - **Document parsing** — PDF (fast PyMuPDF or OCR-capable docling), Markdown, and plain text out of the box; DOCX/PPTX when the docling backend is enabled — with optional NVIDIA GPU acceleration. @@ -41,7 +41,7 @@ ```mermaid flowchart LR Browser --> Nginx["Nginx UI · :3000"] - Nginx --> API["API · :8000
REST + MCP/SSE"] + Nginx --> API["API · :8000
REST + MCP/HTTP"] API --> Redis[("Redis
broker + pub/sub")] API --> DB[("ParadeDB
pgvector + BM25")] API --> Store["Object storage
local / S3 / MinIO"] @@ -289,8 +289,8 @@ EmbedBase exposes an MCP server over **streamable HTTP** at endpoint carries the `/api` prefix; note the trailing slash). Claude Desktop bridges to a *remote* HTTP server via [`mcp-remote`](https://www.npmjs.com/package/mcp-remote). Add to -`~/.config/claude/claude_desktop_config.json` (or `%APPDATA%\Claude\claude_desktop_config.json` -on Windows): +`~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or +`%APPDATA%\Claude\claude_desktop_config.json` (Windows): ```json { @@ -338,7 +338,7 @@ Host ports are configurable in `.env` (change them if the defaults conflict; run | Port | Service | `.env` var | Notes | |---|---|---|---| | `3000` | Nginx / UI | `UI_PORT` | Primary entrypoint. | -| `8000` | API | `API_PORT` | REST + MCP/SSE. Remove this mapping on shared networks (Nginx is the only ingress). | +| `8000` | API | `API_PORT` | REST + MCP/HTTP. Remove this mapping on shared networks (Nginx is the only ingress). | | `5432` | ParadeDB | `POSTGRES_HOST_PORT` | Bound to `127.0.0.1` for a local DB GUI; never exposed on the LAN. | | `9000` / `9001` | MinIO API / console | `MINIO_PORT` / `MINIO_CONSOLE_PORT` | Only with `docker-compose.minio.yml`. | diff --git a/api/main.py b/api/main.py index f7e429c..c071def 100644 --- a/api/main.py +++ b/api/main.py @@ -239,7 +239,7 @@ def create_app() -> FastAPI: # are registered so their routes exist to filter). _register_reference(app) - # MCP server (Delivery 4) — a mounted SSE ASGI sub-app, not a normal router. + # MCP server (Delivery 4) — a mounted streamable-HTTP ASGI sub-app, not a normal router. # Mount last so its /mcp prefix never shadows the REST routes above. mcp.mount_mcp(app, _load_app_config().mcp) diff --git a/api/routers/mcp.py b/api/routers/mcp.py index 54e7a2c..2116bdb 100644 --- a/api/routers/mcp.py +++ b/api/routers/mcp.py @@ -14,5 +14,5 @@ def mount_mcp(app: FastAPI, mcp_config: MCPConfig) -> None: - """Mount the MCP SSE app onto ``app`` (delegated to the service layer).""" + """Mount the MCP streamable-HTTP app onto ``app`` (delegated to the service layer).""" mount_app(app, mcp_config)