How we exposed our docs as a grounded MCP server (Cloudflare AI Search + a stateless Worker)

Martin Liu — Tue, 13 Oct 2026 03:39:33 +0000

LLMs hallucinate most confidently about exactly the domain we publish on — Chinese
licenses, store policies, cloud partitions. I run chinaready.co, an editorial site
about China market entry for Western software teams (full disclosure: it's my site;
the server below is free and MIT-licensed, no account needed). This post documents
how we turned that corpus into a public MCP server anyone can add to their AI
client — and the protocol and platform quirks we hit along the way.

What we built

An endpoint your MCP client can use right now:

https://mcp.chinaready.co/mcp

Three read-only tools:

Tool	What it does
search	Hybrid (BM25 + vector) search; ranked excerpts, each with its absolute source URL
list_topics	Topic catalog with example queries and hub pages
get_article	Any site page as clean Markdown

I verified the flow end-to-end in Cursor and opencode: exact terms like "B25"
(the ICP license threshold) land on the right article, answers carry full
chinaready.co URLs to cite.

Install snippets are on our docs page (Cursor and VS Code have working one-click
links): https://chinaready.co/docs/api/

1. Retrieval: why hybrid matters

The corpus is ~2,700 chunks extracted at build time from published guides
(legal pages and forms excluded). Retrieval runs on Cloudflare AI Search
(https://developers.cloudflare.com/ai-search/).

We started vector-only. That misses exact terms — a query for "B25" (a specific
license threshold) returned semantically-near-but-wrong articles. Switching the
index to hybrid (BM25 keyword + vector, RRF fusion) made exact-term queries land
first try. If your corpus has codes, product names, or policy numbers, hybrid
is not optional.

2. The MCP layer: a stateless Worker, no SDK

Cloudflare AI Search hosts an MCP endpoint itself, but it couldn't give us two
things some clients and directories expect: tool annotations (readOnlyHint,
title) and a branded serverInfo.name (it reports "Cloudflare AI Search").

So the public endpoint is a thin wrapper — a stateless Cloudflare Worker
implementing Streamable HTTP JSON-RPC directly (initialize / tools/list /
tools/call), about 300 lines, no SDK and no session state:

https://github.com/chinaready/mcp

Stateless JSON responses (no SSE stream) turned out to be fine for every client
we tested; the MCP spec allows both.

3. Tool design for citations

The rule we settled on: every machine-readable result carries a human-checkable
absolute URL. search dedupes chunks to article level and prints title + URL +
relevance + snippet; get_article returns Markdown negotiated via
Accept: text/markdown (with an HTML-stripping fallback for subrequests that
skip the converter).

4. Discovery surfaces

llms.txt with the endpoints: https://chinaready.co/llms.txt
MCP server card: /.well-known/mcp/server-card.json
OpenAPI 3.1 for the REST side: /openapi.json
A plain REST search endpoint for agents that don't speak MCP: https://search.chinaready.co/search

Gotchas (the honest list)

Every configuration PUT on AI Search triggers a full corpus re-index — batch your config changes.
The hosted endpoint's rate limit is aggregate across all callers, not per-IP.
The hosted MCP endpoint can't emit tool annotations; if you need them, you're writing a wrapper too.
Worker subrequests to your own zone may not get the zone's Markdown converter — keep a fallback.

The wrapper is MIT and makes a decent template if you want to expose your own
docs the same way. Questions and PRs welcome.