Call Desearch from a Cloudflare Agents MCP client

    Call Desearch from a Cloudflare Agents MCP client

    Tested 17 November 2026.

    For developers evaluating the Cloudflare Agents SDK as an MCP client. This example runs an Agent inside the local Workers runtime, discovers Desearch tools over Streamable HTTP and invokes web-search directly. It uses the hosted Desearch MCP endpoint.

    Tested versions: agents 0.33.0, Wrangler 4.164.0, Miniflare 5.20261117.0-beta and esbuild 0.28.2, fixed by the accompanying npm lock. The hosted Desearch server does not expose a pinned package version in this test; the successful endpoint check was on 17 November 2026.

    Before you begin

    Use Node.js 24.16.0 and npm on macOS with Apple Silicon, the environment tested here. You need network access to npm and https://mcp.desearch.ai/mcp, plus a Desearch API key with available credits. Set DESEARCH_API_KEY in your shell through your secret manager before running the example. Keep it out of source files.

    This local evaluation does not require a Cloudflare login or deployment. It does not establish production Workers plan requirements or catalog inclusion at mcp.cloudflare.com. Desearch API calls use your account credits; check Desearch pricing for current rates.

    Keep the accompanying assets directory beside this guide. Run the following commands in that directory.

    Download the assets

    Save these files in an assets folder in your working directory, keeping the paths shown:

    Install the pinned dependencies

    bash
    mkdir -p cloudflare cp assets/cloudflare/package.json cloudflare/package.json cp assets/cloudflare/package-lock.json cloudflare/package-lock.json npm ci --prefix cloudflare

    Create the local Agent

    Save this as cloudflare/worker.js:

    javascript
    import { Agent } from 'agents'; export class SearchAgent extends Agent { async onRequest(request) { const authorization=request.headers.get('Authorization'); if (!authorization) return new Response('Missing local test authorization',{status:401}); try { const {id}=await this.mcp.connect('https://mcp.desearch.ai/mcp',{ transport:{type:'streamable-http',requestInit:{headers:{Authorization:authorization}}} }); const tools=this.mcp.listTools(); if (!tools.some(t=>t.name.includes('web-search'))) throw new Error('Search tool missing'); const result=await this.mcp.callTool({serverId:id,name:'web-search',arguments:{query:'Python official documentation'}}); if (result.isError) throw new Error('Upstream tool error'); const payload=JSON.parse(result.content.find(c=>c.type==='text').text); const first=payload.data[0]; if (!first.title||!first.link) throw new Error('Missing titled result'); return Response.json({title:first.title,link:first.link,discoveredTools:tools.map(t=>t.name)}); } finally {await this.mcp.closeAllConnections();} } } export default {async fetch(request,env){return env.SEARCH.get(env.SEARCH.idFromName('test')).fetch(request);}};

    The local wrapper forwards the bearer token from the in-memory request into the upstream MCP connection. It closes that connection after the call. The example below disables persistent Durable Object storage; no credentials are added to a deployment configuration or saved to a persistent database.

    Save this as cloudflare/search.mjs:

    javascript
    import {build} from 'esbuild'; import {Miniflare,convertV4MiniflareOptions} from 'miniflare'; import {fileURLToPath} from 'node:url'; if (!process.env.DESEARCH_API_KEY) throw new Error('DESEARCH_API_KEY is required'); const root=fileURLToPath(new URL('.',import.meta.url)); const output=await build({entryPoints:[root+'worker.js'],bundle:true,write:false,format:'esm',platform:'node',conditions:['workerd','worker','browser'],external:['cloudflare:*','node:*'],banner:{js:'import {createRequire} from "node:module";const require=createRequire(import.meta.url);'},logLevel:'silent'}); const mf=new Miniflare(convertV4MiniflareOptions({script:output.outputFiles[0].text,modules:true,compatibilityDate:'2026-11-17',compatibilityFlags:['nodejs_compat'],durableObjects:{SEARCH:{className:'SearchAgent',useSQLite:true}},durableObjectsPersist:false,cachePersist:false,kvPersist:false})); try { const unauth=await mf.dispatchFetch('http://localhost/search'); if(unauth.status!==401)throw new Error('Expected local 401'); const response=await mf.dispatchFetch('http://localhost/search',{headers:{Authorization:'Bearer '+process.env.DESEARCH_API_KEY}}); if(!response.ok)throw new Error('Agent call status '+response.status+': '+await response.text()); console.log(JSON.stringify({unauthenticated_status:unauth.status,...await response.json()},null,2)); } finally {await mf.dispose();}

    Run a search

    bash
    node cloudflare/search.mjs

    Success prints unauthenticated_status: 401 for the local wrapper's missing-header check, a list of discovered tools containing web-search, and a nonempty title and link from Desearch. The live test returned Our Documentation | Python.org; the returned link began /go/v1/, a Desearch redirect path. Titles, tool catalogs and redirect tokens can change.

    The local 401 check covers the example's wrapper. It does not test the hosted endpoint's unauthenticated response. Successful discovery alone does not establish that a Desearch API key can perform searches; this example validates a real result after discovery.

    Troubleshooting

    A missing environment variable stops the launcher with DESEARCH_API_KEY is required. For a rejected key or insufficient credits, verify the Desearch key and balance before retrying. Do not print authorization headers while diagnosing a connection.

    The tested Miniflare 5 release changes its configuration schema. The example uses its exported convertV4MiniflareOptions helper with the exact lock. Passing the older options directly fails validation. The bundler also requires Node compatibility and the createRequire shim shown above. Use the complete pinned setup when reproducing the test.

    This guide validates local Workers execution and native SDK calls. Follow Cloudflare's deployment documentation separately when building a persistent or deployed application.

    Official references