MCP Worker
A Streamable HTTP MCP server for agents at POST /mcp. It needs a bearer token and fails closed. Tools: list_repos, search, get_file, ask and corpus_status, plus corpus:// resources.
Open source. Runs on your own Cloudflare account.
Search your repos and docs, for agents and for people.
search-mcp is an open-source toolkit for Cloudflare AI Search. It copies the files from your git repos to R2, and AI Search indexes them. Agents query the index over MCP. People ask questions through a streaming endpoint and a widget on your docs site.
How the data moves
- git repos
- sync.mjs
- R2 bucket
- AI Search instance
- /ask and /mcp
The sync uploads only git-tracked files. AI Search indexes the bucket. Two Workers read the same index: one for browsers and one for agents. You can also give each Worker its own instance, so that browser answers and agent retrieval use different corpora.
The parts
Query Worker
POST /ask streams an answer for a browser. It has a CORS allowlist, an optional Turnstile check and a per-IP rate limit. Other Workers on your account can call it through the SearchEntrypoint service binding.
Ask widget
One script and one stylesheet that you copy to your docs site. It shows the streamed answer and its sources. With a corpus manifest, sources show as titles and links instead of storage keys.
Corpus sync
Two CLIs, search-mcp-sync and search-mcp-sync-run, upload git-tracked files to R2 and start a reindex. They rename TypeScript, Dockerfiles and other text files that AI Search would skip, so those files are indexed too.
Design choices
- The MCP Worker fails closed. With no
MCP_TOKEN, or a wrong bearer token, it refuses the request. A token can carry a name, so logs show which consumer called. - An allowlist must match something.
includePathsadmits only the paths you list. An entry that matches no files stops the sync before it uploads or deletes anything, so a typo cannot empty a live corpus. - Skipped files are reported. Files over the size cap are listed at the end of each run, and
--fail-on-skipmakes an incomplete corpus a failed run. - A reindex waits its turn. The sync runner waits for a running reindex job and for the AI Search cooldown, so the job it starts sees every file it uploaded.
- No sources, no confident answer. When a question retrieves no sources, the widget shows your empty-corpus text. An upstream error shows as an error, not as an empty result.
Current release
These pages document search-mcp v0.7.0. It adds SearchEntrypoint, a named RPC entrypoint on the query Worker. See the changelog for every release.
The CLIs and the widget files are on npm as @skyphusion/search-mcp. The unscoped name search-mcp on npm belongs to a different project. The Workers deploy from a clone of the repository.
search-mcp is free software under the AGPL-3.0.