Call Desearch web search through ContextForge

    Call Desearch web search through ContextForge

    Tested 17 November 2026.

    For developers evaluating IBM ContextForge as a local MCP gateway. This example registers a pinned local Desearch MCP server, discovers the gateway's search tool and invokes it through ContextForge's JSON-RPC API.

    Tested versions: mcp-contextforge-gateway 1.1.1 and Desearch MCP server 0.3.3. The local open-source path requires no hosted gateway account. Desearch API requests use your account credits.

    Before you begin

    Use Node.js 24.16.0, Python 3.12.13 and uv 0.12.1. These examples were tested on macOS with Apple Silicon on 17 November 2026. You need a Desearch API key with available credits, and network access to the npm and Python package registries and Desearch. Set DESEARCH_API_KEY in your shell using your secret manager before running the example. Keep it out of source files.

    Desearch API requests use your account credits. Check Desearch pricing for current rates. This example calls the web-search tool once. Search titles and links can change between runs.

    Keep the accompanying assets folder beside this guide. Run the commands in that directory. The package lock fixes Desearch MCP server 0.3.3 and its npm dependencies. The Python lock fixes the tested dependency set.

    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 server cp assets/desearch-mcp-server/package.json server/package.json cp assets/desearch-mcp-server/package-lock.json server/package-lock.json npm ci --prefix server uv venv --python 3.12.13 contextforge-venv uv pip sync --python contextforge-venv/bin/python assets/contextforge.lock

    This is a disposable local evaluation. It binds services to loopback, creates random gateway passwords and signing/encryption secrets in memory, and uses an in-memory SQLite database. The upstream key is registered with bearer authentication in that temporary database. No credentials are written into configuration files. Stopping the process removes its registration and gateway credentials.

    The SQLite connection named keeper keeps the shared in-memory database alive while ContextForge's bootstrap opens and closes its own connections. Omitting it caused missing-table errors in this test. The fixture enables SSRF_ALLOW_LOCALHOST so the gateway can reach the local MCP server. Use the product's deployment documentation when configuring a persistent gateway.

    Run a search

    Save this as contextforge_search.py in the same directory:

    python
    import json, os, secrets, subprocess, threading, time from pathlib import Path import httpx root=Path.cwd() key=os.environ['DESEARCH_API_KEY'] env=dict(os.environ,JWT_SECRET_KEY=secrets.token_urlsafe(48),AUTH_ENCRYPTION_SECRET=secrets.token_urlsafe(48),PLATFORM_ADMIN_PASSWORD=secrets.token_urlsafe(32),BASIC_AUTH_PASSWORD=secrets.token_urlsafe(32),DEFAULT_USER_PASSWORD=secrets.token_urlsafe(32),DATABASE_URL='sqlite:///file:desearch?mode=memory&cache=shared&uri=true',SSRF_ALLOW_LOCALHOST='true',LOG_LEVEL='ERROR',LOG_TO_FILE='false',CACHE_TYPE='memory',MCPGATEWAY_UI_ENABLED='false',MCPGATEWAY_ADMIN_API_ENABLED='true') env.pop('DESEARCH_API_KEY',None) server_env=dict(env,HOST='127.0.0.1',PORT='19966') server=subprocess.Popen(['node',str(root/'server/node_modules/desearch-mcp-server/build/index.js'),'--http'],env=server_env,stdout=subprocess.DEVNULL,stderr=subprocess.DEVNULL) logs=[] gateway=subprocess.Popen([str(root/'contextforge-venv/bin/python'),'-c',"import sqlite3,uvicorn; keeper=sqlite3.connect('file:desearch?mode=memory&cache=shared',uri=True); uvicorn.run('mcpgateway.main:app',host='127.0.0.1',port=19969,log_level='error')"],env=env,stdout=subprocess.PIPE,stderr=subprocess.STDOUT,text=True) threading.Thread(target=lambda:logs.extend(gateway.stdout),daemon=True).start() try: with httpx.Client(timeout=60) as client: for _ in range(600): if gateway.poll() is not None:raise RuntimeError('Gateway exited: '+''.join(logs[-20:])) try: if client.get('http://127.0.0.1:19969/health').status_code==200:break except httpx.ConnectError:pass time.sleep(.1) else:raise RuntimeError('Gateway readiness timeout: '+''.join(logs[-15:])) login=client.post('http://127.0.0.1:19969/auth/login',json={'email':'admin@example.com','password':env['PLATFORM_ADMIN_PASSWORD']}) if login.status_code!=200:raise RuntimeError('Login: '+str(login.status_code)+' '+login.text+' Logs: '+''.join(logs[-10:])) token=login.json()['access_token'] client.headers['Authorization']='Bearer '+token unauth=httpx.get('http://127.0.0.1:19969/tools',timeout=10) assert unauth.status_code in (401,403),unauth.status_code created=client.post('http://127.0.0.1:19969/gateways',json={'name':'desearch','url':'http://127.0.0.1:19966/mcp','transport':'STREAMABLEHTTP','auth_type':'bearer','auth_token':key}) if created.status_code not in (200,201):raise RuntimeError('Registration: '+str(created.status_code)+' '+created.text+' Logs: '+''.join(logs[-10:])) listed=client.get('http://127.0.0.1:19969/tools');listed.raise_for_status() data=listed.json(); tools=data.get('tools',data) if isinstance(data,dict) else data tool=next(t for t in tools if 'web-search' in t['name']) result=client.post('http://127.0.0.1:19969/rpc',json={'jsonrpc':'2.0','id':1,'method':'tools/call','params':{'name':tool['name'],'arguments':{'query':'Python official documentation'}}}) result.raise_for_status();body=result.json() assert 'error' not in body,body result_body=body['result'];assert not result_body.get('isError'),result_body payload=json.loads(next(c['text'] for c in result_body['content'] if c['type']=='text')) first=payload['data'][0];assert first['title'] and first['link'] print(json.dumps({'gateway_version':'1.1.1','unauthenticated_tools_status':unauth.status_code,'discovered_tool':tool['name'],'title':first['title'],'link':first['link']},indent=2)) except Exception as exc: message=str(exc) for secret in [key,*[env[n] for n in ('JWT_SECRET_KEY','AUTH_ENCRYPTION_SECRET','PLATFORM_ADMIN_PASSWORD','BASIC_AUTH_PASSWORD','DEFAULT_USER_PASSWORD')],locals().get('token','')]: if secret:message=message.replace(secret,'[REDACTED]') raise RuntimeError(message) from None finally: gateway.terminate();server.terminate();gateway.wait(timeout=15);server.wait(timeout=10)

    Run with DESEARCH_API_KEY already set by your secret manager:

    bash
    contextforge-venv/bin/python contextforge_search.py

    Success prints the discovered tool desearch-web-search, unauthenticated_tools_status: 401, and a nonempty title and link. The test returned Python 3.15.2 documentation and a Desearch redirect path beginning /go/v1/. Result content and redirect tokens can change. The example terminates both child processes after the call.

    Troubleshooting

    Keep loopback ports 19966 and 19969 free. Readiness failure means the local gateway did not become available; check the pinned lock and port availability before retrying.

    ContextForge 1.1.1 validates its JWT secret, encryption secret and default/admin passwords at startup. Use the generated values in this example together. It authenticates through the local /auth/login endpoint and keeps its returned token in memory. admin@example.com is the gateway's documented local bootstrap username, not a hosted account signup.

    The gateway prefixes the upstream tool name. Invoke the discovered desearch-web-search, not the upstream web-search name. Discovery alone does not validate a Desearch key: the upstream server permits discovery but returns HTTP 401 with isError: true for an unauthenticated tool call. For a rejected key or insufficient credits, check your Desearch key and account balance before retrying.

    Official references