Connect Desearch through SuperGateway

    Connect Desearch through SuperGateway

    Tested 17 November 2026.

    For developers whose client needs stdio while the Desearch server uses Streamable HTTP. This example starts Desearch on loopback, runs SuperGateway as a stdio bridge, and validates the bridge with a FastMCP client. It tests SuperGateway only.

    Tested versions: SuperGateway 4.2.2; FastMCP 4.2.0 with MCP SDK 2.3.0 in the client environment. Desearch MCP server: 0.3.3.

    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 .venv uv pip sync --python .venv/bin/python assets/fastmcp.lock mkdir -p supergateway cp assets/supergateway/package.json supergateway/package.json cp assets/supergateway/package-lock.json supergateway/package-lock.json npm ci --prefix supergateway

    Run a search

    Save this as supergateway_search.py in the same directory:

    python
    import asyncio import json import os import subprocess from pathlib import Path import httpx from fastmcp import Client from fastmcp.client.transports import StdioTransport async def main(): key = os.environ["DESEARCH_API_KEY"] env = dict(os.environ, HOST="127.0.0.1", PORT="19966") env.pop("DESEARCH_API_KEY", None) server = subprocess.Popen( ["node", str(Path("server/node_modules/desearch-mcp-server/build/index.js").resolve()), "--http"], env=env, stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL, ) try: async with httpx.AsyncClient() as http: for _ in range(100): if server.poll() is not None: raise RuntimeError("Local Desearch server exited") try: response = await http.get("http://127.0.0.1:19966/health") if response.status_code == 200: break except httpx.ConnectError: pass await asyncio.sleep(0.1) else: raise RuntimeError("Local server did not become ready") transport = StdioTransport( command="node", args=[str(Path("supergateway/node_modules/supergateway/dist/index.js").resolve()), "--streamableHttp", "http://127.0.0.1:19966/mcp", "--outputTransport", "stdio", "--oauth2Bearer", key, "--logLevel", "none"], keep_alive=False, ) async with Client(transport, timeout=60, mode="legacy") as client: result = await client.call_tool("web-search", {"query": "Python official documentation"}) payload = json.loads(next(block.text for block in result.content if block.type == "text")) first = payload["data"][0] assert first["title"] and first["link"] print(json.dumps({"title": first["title"], "link": first["link"]}, indent=2)) finally: server.terminate() server.wait(timeout=10) asyncio.run(main())

    Run it with your API key already present in the environment:

    bash
    .venv/bin/python supergateway_search.py

    A successful run prints JSON containing a nonempty title and link. The test returned Our Documentation | Python.org. The returned link began with /go/v1/; treat it as a Desearch redirect path, rather than a canonical source URL. The response order and redirect token can change. The example stops its child processes on exit.

    Troubleshooting

    A missing DESEARCH_API_KEY environment variable stops the example before a search. Starting the stdio Desearch server directly without it produces DESEARCH_API_KEY environment variable is required and a nonzero exit. HTTP discovery can succeed without credentials: tools/list returned 200, while an unauthenticated tools/call returned HTTP 401 with isError: true and instructions to send a bearer token or x-api-key. Successful discovery alone does not prove search access. For a rejected key or insufficient credits, verify the key and account balance before retrying.

    The example supplies --oauth2Bearer to authenticate upstream requests and disables gateway logging. It uses legacy MCP negotiation for the bridge. The key is passed to a child process at runtime; do not paste it into a saved configuration or command. This test uses only the Streamable HTTP to stdio route.

    The example requires unused loopback ports 19966. A startup failure can mean a port is already occupied. It binds to 127.0.0.1 and is intended for a local test.

    Official references