@@ -47,6 +47,16 @@ async def dispatch(self, request: Request, call_next):
         if not redis_client:
             return await call_next(request)
 
+        # Internal callers — the hosted fojin-mcp container, compose
+        # healthchecks — reach this port over the docker network or loopback.
+        # The only public path is nginx, and nginx always appends
+        # X-Forwarded-For, so a request without that header cannot have come
+        # from the internet. Per-IP limiting such traffic is worse than
+        # useless: every internal caller shares one 172.x address, so all
+        # fojin-mcp users would burn a single /api/search/semantic budget.
+        if "x-forwarded-for" not in request.headers:
+            return await call_next(request)
+
         # Behind Nginx reverse proxy, request.client.host is always the
         # internal Docker IP. Use the shared helper to extract the real
         # client IP from X-Forwarded-For — taking the LAST entry, since
 
@@ -0,0 +1,68 @@
+"""Internal (no-X-Forwarded-For) traffic must bypass the per-IP rate limiter.
+
+The only public route to the backend is nginx, which always appends
+X-Forwarded-For. Direct docker-network callers — the hosted fojin-mcp
+container, compose healthchecks — carry no XFF and all share one internal
+address, so keying them into the per-IP window would make every fojin-mcp
+user worldwide share a single /api/search/semantic budget (20/min): the
+hosted MCP endpoint would 429 itself to death on day one.
+"""
+
+from types import SimpleNamespace
+
+import pytest
+from starlette.requests import Request
+from starlette.responses import PlainTextResponse
+
+from app.core.rate_limit import RateLimitMiddleware
+
+
+class _FakeRedis:
+    def __init__(self):
+        self.incr_calls = 0
+
+    async def incr(self, key):
+        self.incr_calls += 1
+        return 1
+
+    async def expire(self, key, ttl):
+        return True
+
+
+def _request(headers: dict[str, str], redis) -> Request:
+    scope = {
+        "type": "http",
+        "method": "GET",
+        "path": "/api/search/semantic",
+        "headers": [(k.lower().encode(), v.encode()) for k, v in headers.items()],
+        "query_string": b"",
+        "client": ("172.18.0.9", 40000),
+        "app": SimpleNamespace(state=SimpleNamespace(redis=redis)),
+    }
+    return Request(scope)
+
+
+async def _ok(_request):
+    return PlainTextResponse("ok")
+
+
+@pytest.mark.asyncio
+async def test_no_xff_skips_rate_limiting():
+    """No X-Forwarded-For ⇒ internal caller ⇒ no redis window consumed."""
+    redis = _FakeRedis()
+    mw = RateLimitMiddleware(app=None)
+    resp = await mw.dispatch(_request({}, redis), _ok)
+    assert resp.status_code == 200
+    assert redis.incr_calls == 0
+
+
+@pytest.mark.asyncio
+async def test_xff_traffic_still_rate_limited():
+    """Anything nginx forwarded keeps consuming its per-IP window."""
+    redis = _FakeRedis()
+    mw = RateLimitMiddleware(app=None)
+    resp = await mw.dispatch(
+        _request({"X-Forwarded-For": "1.2.3.4, 5.6.7.8"}, redis), _ok
+    )
+    assert resp.status_code == 200
+    assert redis.incr_calls == 1
@@ -160,3 +160,38 @@ server {
     server_name stream.fojin.ai;
     return 301 https://$host$request_uri;
 }
+
+# mcp.fojin.ai — hosted MCP endpoint (behind Cloudflare proxy, HTTP only).
+# Unlike stream.fojin.ai this CAN sit behind Cloudflare: the MCP server runs
+# stateless JSON request/response (json_response=True — no long SSE streams),
+# so CF's 125s proxy timeout and response buffering never come into play.
+# The container does its own per-client rate limiting keyed on
+# CF-Connecting-IP (passed through by proxy_pass untouched).
+server {
+    listen 80;
+    server_name mcp.fojin.ai;
+    include /etc/nginx/cloudflare-real-ip.conf;
+
+    add_header X-Content-Type-Options "nosniff" always;
+
+    location = /healthz {
+        proxy_pass http://127.0.0.1:8765;
+        proxy_set_header Host $host;
+    }
+
+    location = /mcp {
+        # Matches the MCP server's own 4 MB request-body cap.
+        client_max_body_size 4m;
+        proxy_pass http://127.0.0.1:8765;
+        proxy_http_version 1.1;
+        proxy_set_header Host $host;
+        proxy_set_header X-Real-IP $remote_addr;
+        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+        proxy_set_header X-Forwarded-Proto $scheme;
+        proxy_read_timeout 120s;
+    }
+
+    location / {
+        return 404;
+    }
+}
@@ -296,6 +296,36 @@ services:
       # a proxy can set FRONTEND_BIND=0.0.0.0.
       - "${FRONTEND_BIND:-127.0.0.1}:${FRONTEND_PORT:-3000}:80"
 
+  # Hosted MCP endpoint (mcp.fojin.ai) — fojin's corpus tools for AI agents.
+  # Talks to the backend directly over the compose network (no nginx hop):
+  # internal traffic carries no X-Forwarded-For, which is what exempts it from
+  # the backend's per-IP limiter (app/core/rate_limit.py) — this container
+  # runs its own per-client window keyed on CF-Connecting-IP instead.
+  mcp:
+    build:
+      context: ./mcp-server
+      dockerfile: Dockerfile
+    container_name: fojin-mcp
+    restart: always
+    logging: *default-logging
+    mem_limit: 192m
+    cpus: 0.25
+    environment:
+      FOJIN_API_BASE_URL: http://backend:8000/api
+      FOJIN_MCP_PUBLIC_HOSTS: ${FOJIN_MCP_PUBLIC_HOSTS:-mcp.fojin.ai}
+      FOJIN_MCP_RATE_LIMIT: ${FOJIN_MCP_RATE_LIMIT:-30}
+    ports:
+      - "127.0.0.1:${MCP_PORT:-8765}:8765"
+    healthcheck:
+      test: ["CMD", "python", "-c", "import urllib.request; urllib.request.urlopen('http://localhost:8765/healthz')"]
+      interval: 30s
+      timeout: 5s
+      retries: 5
+      start_period: 10s
+    depends_on:
+      backend:
+        condition: service_healthy
+
 volumes:
   pgdata:
   esdata:
 
@@ -0,0 +1,21 @@
+# Hosted fojin-mcp (mcp.fojin.ai) — streamable-HTTP MCP endpoint.
+# The stdio install path for end users stays PyPI (`uvx fojin-mcp`); this
+# image only exists so docker-compose can run the hosted endpoint.
+FROM python:3.12-slim
+
+WORKDIR /srv/fojin-mcp
+
+# Package metadata + source only; tests/CI never enter the image.
+COPY pyproject.toml README.md ./
+COPY fojin_mcp ./fojin_mcp
+
+RUN pip install --no-cache-dir ".[http]" && \
+    useradd --system --no-create-home fojin-mcp
+
+USER fojin-mcp
+
+EXPOSE 8765
+
+# --host 0.0.0.0 is container-internal only: compose publishes the port
+# bound to the host's loopback, nginx/Cloudflare are the public path.
+CMD ["fojin-mcp", "--transport", "streamable-http", "--host", "0.0.0.0", "--port", "8765"]
@@ -9,6 +9,17 @@ instead of inventing scripture.
 
 Read-only by construction: it only issues GETs against fojin's public API.
 
+Two ways to use it:
+
+1. **Hosted endpoint (zero install)** — `https://mcp.fojin.ai/mcp`, streamable
+   HTTP, anonymous, rate-limited. One line in Claude Code:
+
+   ```bash
+   claude mcp add --transport http fojin https://mcp.fojin.ai/mcp
+   ```
+
+2. **Local over stdio** — `uvx fojin-mcp`, the classic MCP install (below).
+
 ## Tools
 
 | Tool | What it returns |
@@ -70,7 +81,35 @@ from a checkout.) Restart Claude Desktop; the six fojin tools then appear.
 ### ChatGPT / other MCP clients
 
 Any client that speaks MCP over stdio can launch `uvx fojin-mcp` (or the
-`fojin-mcp` console script) and will discover the six tools automatically.
+`fojin-mcp` console script); any client that speaks streamable HTTP can point
+at `https://mcp.fojin.ai/mcp`. Both discover the six tools automatically.
+
+## Hosting the HTTP endpoint (self-host)
+
+The same package serves streamable HTTP (requires the `http` extra, which adds
+uvicorn):
+
+```bash
+pip install 'fojin-mcp[http]'
+fojin-mcp --transport streamable-http --port 8765 --public-host mcp.example.com
+```
+
+The hosted mode is **stateless JSON request/response** (`stateless_http` +
+`json_response`): every tool call is one plain POST — no SSE streams, so it
+sits safely behind Cloudflare's proxy and behind multi-worker uvicorn. It adds:
+
+- **Per-client rate limiting** — sliding window keyed on `CF-Connecting-IP` /
+  `X-Real-IP` (falling back to the socket peer). Tune with
+  `--rate-limit`/`--rate-window` or `FOJIN_MCP_RATE_LIMIT`/`FOJIN_MCP_RATE_WINDOW`.
+- **Host-header validation** (DNS-rebinding protection) pinned to
+  `--public-host` / `FOJIN_MCP_PUBLIC_HOSTS` (default `mcp.fojin.ai`).
+- **Access + tool logs** — one JSON line per request (`fojin_mcp.access`) and
+  per tool call (`fojin_mcp.tools`) on stdout/stderr.
+- **`/healthz`** for container/proxy healthchecks.
+
+The production deployment is the `mcp` service in the repo's
+`docker-compose.yml` (it talks to the backend container directly) plus the
+`mcp.fojin.ai` server block in `deploy/host-nginx/fojin.conf`.
 
 ## Design
 
@@ -83,7 +122,9 @@ Any client that speaks MCP over stdio can launch `uvx fojin-mcp` (or the
   `get_parallels` enriches each parallel's URN via a bounded, concurrent,
   best-effort `text_id → cbeta_id` lookup (a miss just leaves `urn: null`).
 - **Testable core.** All HTTP + reshaping lives in `client.py` and is tested
-  against a mocked transport; `server.py` is a thin FastMCP wiring layer.
+  against a mocked transport; `server.py` is a thin MCP wiring layer (SDK v2 —
+  `mcp>=2` is required; 2.0 removed the 1.x module this package imported
+  through 0.1.0), and the hosted-edge concerns live in `http.py`.
 - **Fails soft.** An upstream error returns `{"error": "..."}` to the model
   rather than crashing the tool call.
 
@@ -101,7 +142,7 @@ every change under `mcp-server/`. To release to PyPI, bump `version` in
 `pyproject.toml`, then push a tag:
 
 ```bash
-git tag mcp-v0.1.0 && git push origin mcp-v0.1.0
+git tag mcp-v0.2.0 && git push origin mcp-v0.2.0
 ```
 
 `.github/workflows/mcp-publish.yml` builds and uploads. It needs credentials
 
@@ -1,3 +1,4 @@
-"""fojin MCP server package — cross-canon Buddhist corpus tools over stdio."""
+"""fojin MCP server package — cross-canon Buddhist corpus tools over stdio or
+streamable HTTP (the hosted endpoint at mcp.fojin.ai)."""
 
-__version__ = "0.1.0"
+__version__ = "0.2.0"
@@ -57,6 +57,9 @@ def __init__(
             timeout=timeout, headers={"User-Agent": USER_AGENT}
         )
         self._owns_client = client is None
+        # text_id → cbeta_id is static corpus metadata; caching it collapses the
+        # 1+N fan-out of repeated get_parallels calls on a long-lived client.
+        self._cbeta_cache: dict[int, str] = {}
 
     async def __aenter__(self) -> FojinClient:
         return self
@@ -113,12 +116,23 @@ async def get_parallels(self, text_id: int, juan_num: int) -> dict[str, Any]:
         return shaped
 
     async def _text_cbeta_id(self, text_id: int) -> str | None:
-        """Best-effort text_id → cbeta_id via /texts/{id}; None on any failure."""
+        """Best-effort text_id → cbeta_id via /texts/{id}; None on any failure.
+
+        Successful lookups are cached for the client's lifetime (the mapping is
+        static); failures are not, so a transient error can heal on retry."""
+        if text_id in self._cbeta_cache:
+            return self._cbeta_cache[text_id]
         try:
             meta = await self._get(f"/texts/{text_id}")
         except FojinAPIError:
             return None
-        return meta.get("cbeta_id") if isinstance(meta, dict) else None
+        cbeta_id = meta.get("cbeta_id") if isinstance(meta, dict) else None
+        if isinstance(cbeta_id, str) and cbeta_id:
+            if len(self._cbeta_cache) >= 100_000:  # paranoia bound, ~10K texts real
+                self._cbeta_cache.clear()
+            self._cbeta_cache[text_id] = cbeta_id
+            return cbeta_id
+        return None
 
     async def _enrich_parallel_urns(self, parallels: list[dict[str, Any]]) -> None:
         """Fill each parallel's ``urn`` in place from its reader_ref.text_id.
@@ -158,15 +172,19 @@ async def lookup_dictionary(self, term: str, limit: int = 10) -> dict[str, Any]:
 
     async def lookup_entity(self, query: str, limit: int = 10) -> dict[str, Any]:
         """Knowledge-graph entity search (persons, places, works, terms)."""
+        # /kg/entities takes `limit` (not `size` like search/dictionary do);
+        # FastAPI silently drops unknown params, so the wrong name means the
+        # caller's limit never arrives.
         data = await self._get(
-            "/kg/entities", {"q": query, "size": _clamp(limit, 1, 50)}
+            "/kg/entities", {"q": query, "limit": _clamp(limit, 1, 50)}
         )
         return {"query": query, "entities": _as_list(data, "results", "entities")}
 
     async def resolve_urn(self, urn: str) -> dict[str, Any]:
         """Resolve a fojin URN → reader URL + existence (server-authoritative)."""
-        # Anchor '#' must be percent-encoded or the server sees an anchorless URN.
-        return await self._get("/urn/resolve", {"urn": urn.replace("#", "%23")})
+        # httpx percent-encodes '#' in query params; pre-encoding here would
+        # double-encode it into a literal "%23" on the server side.
+        return await self._get("/urn/resolve", {"urn": urn})
 
 
 # ── pure reshaping (unit-tested with plain dicts) ────────────────────────