MCP tool reference: search-mcp

Connect a client

{
  "mcpServers": {
    "search-mcp": {
      "type": "http",
      "url": "https://YOUR_MCP_HOST/mcp",
      "headers": { "Authorization": "Bearer YOUR_TOKEN" }
    }
  }
}

The token is the MCP_TOKEN secret on the Worker. It is one token, or comma-separated name=token pairs, so that logs name each consumer. A missing or wrong token gets HTTP 401. GET /health answers without a token.

Test the Worker from a shell:

curl -sS -H "Authorization: Bearer YOUR_TOKEN" \
  -H "content-type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' \
  "https://YOUR_MCP_HOST/mcp"

Recommended order

Use list_repos, then search, then get_file. Use ask when you want one written answer instead of raw chunks.

Filters are best-effort. In search and ask, the repos, path_prefix and min_score filters apply after a capped fetch from AI Search. The fetch takes only the top-ranked chunks: 4 times max_num_results, at least 20 and at most 50. A narrow filter can return "No results." while matches exist lower in the ranking. If a filtered search is empty, try a more specific query or fewer filters.

list_repos

Lists the repo names in this corpus. Use these exact strings for the repos filter. It takes no arguments.

The names come from the CORPUS_REPOS var when it is set, or else from the prefixes in the CORPUS R2 bucket. If the R2 listing fails, the tool returns an error, not an empty list.

search

Searches the indexed corpus. It returns chunks with repo, path, score and text, at most 2 chunks per file.

Argument	Type	Meaning
`query`	string, required	A natural-language or keyword query.
`max_num_results`	number	The most chunks to return, 1 to 20. Default 8.
`repos`	array of strings	Exact repo names from `list_repos`. Best-effort.
`path_prefix`	string, or array of strings	A path prefix such as `"docs/"`, matched on the path only. Best-effort. An array that holds a non-string is an argument error.
`retrieval_type`	`hybrid`, `keyword` or `vector`	Default `hybrid`. Use `keyword` for identifiers and symbols.
`rewrite`	boolean	AI Search query rewrite. Default on for hybrid and vector, off for keyword.
`min_score`	number	Drops chunks that score below this value, on the 0 to 1 scale from AI Search. Best-effort.
`rerank`	boolean	Upstream reranking, where AI Search supports it. Default off.

get_file

Reads one corpus file from R2 by repo and path. Use it after search when a chunk is not enough. It needs the CORPUS R2 binding. It tries the plain key and the .txt key that the sync uses for renamed files.

Argument	Type	Meaning
`repo`	string, required	The exact repo name.
`path`	string, required	The path in the repo, as in a search result.
`max_bytes`	number	The most bytes to return. Default 65536, hard cap 262144.

ask

Answers a question in prose from the corpus, with a list of sources. It uses retrieval plus one non-streaming generation call. Use search and get_file when you need the raw evidence.

Argument	Type	Meaning
`question`	string, required	The question to answer from the corpus.
`repos`	array of strings	A repo filter on the citation chunks. Best-effort.
`path_prefix`	string, or array of strings	A path prefix filter on the citation chunks.
`max_num_results`	number	The retrieval budget for the answer, 1 to 20. Default 8.

corpus_status

Returns the metadata of the last corpus sync, so an agent can judge how fresh the corpus is. It reads _meta/corpus-status.json, which sync.mjs writes to R2 after each upload. With no R2 binding, it falls back to CORPUS_REPOS. It takes no arguments.

Resources

URI	Type	Content
`corpus://catalog`	`application/json`	The repo list and a short description of this corpus.
`corpus://skill`	`text/markdown`	Instructions for agents on how to use the tools.

The tool definitions are in src/mcp.ts at search-mcp v0.7.0.