By Matija, the developer behind Build with Matija. I run a Next.js MCP server that Claude uses for content research on this site. Tested with Next.js 16.3, TypeScript 5.9, Node 22 and the DeepSeek Search API. Last updated 2026-10-25.
An AI agent doing research gets better sources from one tool call that runs several complementary queries than from one query at a time. To make that work, the tool has to do four things on the server: run the queries with bounded concurrency under one deadline, keep the successful queries when some fail, merge duplicate URLs while recording which queries found each one, and rank the merged list with reciprocal rank fusion plus a soft penalty for repeated domains. This guide shows how I built that as deepseek_search_web in my MCP server, with the TypeScript for each step and the reasons behind the constants.
Why one query per tool call was not enough
My MCP server already had a single-query search tool. When Claude researched a topic for an article, it called that tool again and again with small variations, read the same three documentation pages in every result list, and spent most of its context on duplicates. The search provider I added has no pagination, so asking for "page two" was not an option either. The only way to reach more sources is to ask different questions: a site:github.com query, a quoted error string, a -site: exclusion, a date filter.
That suggested a different tool shape. The agent sends up to ten queries in one call, the server runs them, and the agent gets one deduplicated, ranked list in which every source says which queries found it and at what position. The agent spends its effort on choosing good query angles, and the server does the merging, which is cheap and deterministic in code.
The description does real work here. It tells the agent that more sources come from more query angles and lists the operators that produce them. Without that sentence, agents tend to send ten near-identical phrasings of the same question, which return the same pages.
If you have not built an MCP server yet, start with my guide to building an MCP server in Next.js and come back for the tool itself.
Step 1: Clean the queries before spending money
Every query costs one paid request, so the server cleans the list first. It trims each query, drops empty ones and exact duplicates, enforces the provider's 128-character limit, and only then checks the ten-query cap.
Two details came from tests. The length limit is counted in Unicode code points with [...value].length, because value.length counts UTF-16 units and would reject a 100-character query that contains a few emoji or CJK characters. The duplicate check runs before the cap, so twelve queries with two exact repeats still pass, and the response reports duplicate_queries_removed so the agent can see it happened.
Step 2: Run the queries with a concurrency limit and one deadline
Ten queries fired at once can trip the provider's rate limit, and ten queries run one by one take too long for a serverless function. The server runs them through a small worker pool of four, and every request shares one overall deadline.
The worker pool is a dozen lines and needs no dependency. Each worker takes the next index until the list is empty, and results land in their original positions so the per-query report stays in the order the agent sent.
The deadline matters because each single request already has its own timeout and retries. Without a batch deadline, a slow provider plus retries on ten queries could run for minutes and the function would be killed with nothing returned. AbortSignal.any combines the caller's cancellation with the batch deadline, so either one stops every in-flight request.
Every query catches its own error and returns ok: false. Nothing is thrown out of the pool, so one failed query never discards nine good result lists.
Step 3: Report partial failure instead of hiding it
After the pool finishes, the results split into successes and errors. The call only fails when every query failed. Otherwise the agent gets the merged sources and a list of what went wrong.
The batch_deadline kind separates "this query was cancelled because the whole batch ran out of time" from "the caller cancelled". An agent that sees batch_deadline on three queries knows to resend those three in a smaller call. An empty result list for a query is a success with zero results, which is different information from a failed request, and the response keeps the two apart in per_query.
Step 4: Merge duplicate URLs with provenance
The same page shows up across queries with different tracking parameters, fragments, trailing slashes and parameter orders. The server computes two values per URL: a cleaned display URL to show the agent, and a stricter identity key for deduplication.
Only known tracking parameters are removed. A parameter like ?id=42 or ?page=3 can change which page you get, so it stays in both the display URL and the key. Sorting the parameters and dropping the trailing slash only happen in the key, so the URL the agent fetches later is still the one the site actually linked.
When a key is seen again, the existing entry gains a { query, position } match and keeps the longer snippet and summary and the higher scores. If the same query returned the same page twice, only its best position is kept. The output then tells the agent, for every source, which queries found it.
json
That provenance is useful on its own. A source found by four of six query angles is probably central to the topic, and a source found only by the site:github.com query is probably an implementation example.
Step 5: Rank with reciprocal rank fusion
The provider returns a rerank score for every result, and it is tempting to sort the merged list by it. Those scores are computed relative to one query, so a 2.4 for one query and a 2.4 for another are not comparable. Reciprocal rank fusion avoids the problem by using positions only: each source scores 1 / (k + position) for every query that returned it, and the sum is its rank.
The classic RRF constant is 60. I used 10 because these lists are short and the top few positions are where the quality is. With k = 10, position 1 scores about 0.091 and position 20 about 0.033, so a first-place result clearly beats a twentieth-place one. A source that appears in three lists at mid positions still beats a source that appears once near the top, which is the cross-query agreement I wanted to reward.
The rerank score, the provider's authority value and freshness within the last year each add at most 0.02. That is enough to break ties between sources with similar positions and too small to lift a weak result over a strong one.
Step 6: Diversify domains with a decay instead of a cap
Ranked by RRF alone, a research list on a framework topic is often half official documentation, because the docs rank well for every query. A hard limit of two results per domain fixes that and also throws away the eighth docs page you actually needed. The server applies a soft decay: each additional result from a domain already seen higher up has its score multiplied by 0.85 per earlier appearance.
typescript
= ;
domainSeen = <, >();
diversified = scored
.( {
seen = domainSeen.(source.) ?? ;
domainSeen.(source., seen + );
{ source, score, : score * ** seen };
})
.( b. - a.);
selected = diversified.(, maxSources);
The second result from a domain keeps 85% of its score, the third 72%, the fifth 52%. A docs page that ranked first in four queries stays near the top even as the fifth result from its domain, and a page from the same domain that only scraped into one list falls behind independent sources. The domain is the hostname without www., so docs.example.com and example.com count separately, which suited my research use.
The returned aggregate_score is the RRF score before the decay. The order reflects diversity, and the number still tells the agent how strongly the queries agreed on that source.
Step 7: Return a response the agent can reason about
The final response reports what happened at every stage alongside the sources themselves.
json
truncated with unique_sources_count tells the agent whether raising max_sources would show more. raw_results_count against unique_sources_count shows how much the queries overlapped, which is a hint to choose more different angles next time. Compact mode returns 300-character snippets and no summaries, which keeps a 150-source response small enough to leave room in the context for reading the pages that matter. The search tool never returns page content, so reading is a separate, deliberate step with a fetch tool.
FAQ
Why let the server merge results instead of the model?
Merging 250 results by URL, sorting by a formula and trimming snippets is deterministic work that code does in milliseconds. Done by the model, it costs tokens on every call and comes out slightly different each time.
Why is the RRF constant 10 here and not 60?
60 is the value from the original reciprocal rank fusion paper, which fused long result lists from many retrieval systems. With at most 50 results per query and most of the value in the top ten, a smaller constant gives the top positions more weight.
How do I stop the fetch tool from reaching internal addresses?
Check every URL before passing it on. My fetch tool rejects non-HTTP schemes, credentials in the URL, loopback, private and link-local IPs (including IPv4-mapped IPv6 forms), single-label hostnames and names ending in .local, .internal and similar. It does not resolve DNS, so it is a first line of defence for a request the provider makes on your behalf.
What does a batch cost?
The provider bills per successful request, independent of how many results each returns, so a ten-query batch costs at most ten requests. Deduplicating the queries before sending them is the cheapest saving available.
Can I reuse this with a different search provider?
Yes. Only the deepseekSearch call and the result fields are provider-specific. The query cleanup, the worker pool, the URL key, RRF and the domain decay work with any API that returns ranked lists of URLs.
Conclusion
Research agents waste calls and context when every search is a single query and duplicates come back each time. Moving the fan-out into one MCP tool fixes that: clean the queries, run them four at a time under one deadline, keep partial results, merge URLs on a strict identity key with per-query provenance, rank with reciprocal rank fusion, and soften repeated domains with a decay. The agent ends up choosing query angles and reading sources, and the server handles the merging. If you are exposing your own content to agents as well, my article on expanding a Next.js MCP server with editing and revalidation covers the write side, and the Search Console MCP integration shows another research tool built the same way.
Let me know in the comments if you have questions, and subscribe for more practical development guides.
"Broad web source discovery. Run 1-10 complementary queries in one call (up to 50 results each); returns a deduplicated, ranked source list with matching-query provenance. DeepSeek has no pagination: to find more sources, add query angles such as `site:github.com`, quoted phrases, `-site:`, `lang:de`, `after:2026-01-01`."
queries
array
string
min
1
min
1
max
10
count_per_query
number
int
min
1
max
50
optional
max_sources
number
int
min
1
max
500
optional
detail
enum
"compact"
"detailed"
optional
original_question
string
max
128
optional
async
try
return
jsonTextResult
await
runDeepSeekBatchSearch
queries
queries
/* ... */
catch
return
jsonErrorResult
// File: src/lib/deepseek-search-batch.ts
export
function
prepareQueries
queries: string[]
const
map
(query) =>
trim
filter
Boolean
if
length
0
throw
new
DeepSeekApiError
"Provide at least one non-empty query."
kind
"invalid_request"
const
filter
(query) =>
codePointLength
DEEPSEEK_MAX_QUERY_CHARS
if
length
0
throw
new
DeepSeekApiError
`Each query must be at most ${DEEPSEEK_MAX_QUERY_CHARS} characters.`
kind
"invalid_request"
const
new
Set
if
length
MAX_BATCH_QUERIES
throw
new
DeepSeekApiError
`At most ${MAX_BATCH_QUERIES} distinct queries per call.`
kind
"invalid_request"
return
queries
duplicatesRemoved
length
length
export
function
codePointLength
value: string
return
length
// File: src/lib/deepseek-search-batch.ts
async
function
items
concurrency
number
fn
(item: T, index: number) =>
Promise
Promise
const
new
Array
length
let
0
const
Array
from
length
Math
max
1
Math
min
length
async
while
length
const
await
fn
await
Promise
all
return
// Overall deadline keeps a 10-query batch with retries inside serverless limits.