cxws-mcp

cxws-mcp exposes the Codex standalone cloud-search endpoint as 11 intent-oriented MCP tools. It is a single Rust binary with stdio and MCP Streamable HTTP transports. Each process uses the operator's own API base URL, key, and model.

[!WARNING] /alpha/search is an experimental upstream API. Providers can remove it or change its schema. cxws-mcp fails clearly on incompatible responses and does not silently fall back to another search provider.

Requirements

• Rust 1.88 or newer to build from source
• An OpenAI-compatible provider that implements <base-url>/alpha/search
• A model accepted by that endpoint

Install

cargo install --path .

The binary is named cxws-mcp.

Configuration

Purpose	Environment	CLI	Required
Upstream base URL	CXWS_BASE_URL	--base-url	yes
Upstream API key	CXWS_API_KEY	none	yes
Upstream model	CXWS_MODEL	--model	yes
Log filter	CXWS_LOG	none	no
Expose advanced web_run	CXWS_EXPOSE_WEB_RUN	--expose-web-run	no

CLI base URL and model values override their environment variables. The API key is environment-only so it does not appear in process listings or shell history. Logs go to stderr and never include the key or upstream response bodies.

Base URLs must use HTTPS. Plain HTTP is accepted automatically for localhost and literal loopback addresses; use --allow-insecure-http for any other operator-controlled HTTP endpoint. User information, query strings, and fragments in the base URL are rejected. Upstream redirects are disabled. Reqwest honors standard proxy variables such as HTTPS_PROXY and NO_PROXY.

Example:

export CXWS_BASE_URL='https://api.example.com/v1'
export CXWS_API_KEY='your-provider-key'
export CXWS_MODEL='your-search-capable-model'

Stdio

Start the server directly:

cxws-mcp stdio

Generic MCP client configuration:

{
  "mcpServers": {
    "cxws": {
      "command": "cxws-mcp",
      "args": ["stdio"],
      "env": {
        "CXWS_BASE_URL": "https://api.example.com/v1",
        "CXWS_API_KEY": "your-provider-key",
        "CXWS_MODEL": "your-search-capable-model"
      }
    }
  }
}

Streamable HTTP

Start a loopback listener:

cxws-mcp http --listen 127.0.0.1:8787

Configure the MCP client with:

http://127.0.0.1:8787/mcp

Readiness is available at GET /healthz. The HTTP mode has no TLS or client authentication and defaults to loopback. For remote use, place an authenticated reverse proxy in front of it; see the Nginx guide.

The server supports rmcp's negotiated protocol versions, including stable 2025-11-25 initialization and the 2026-07-28 discovery lifecycle. It does not implement the legacy standalone HTTP+SSE transport.

Tool Selection

Intent	Tool
Fetch a specific HTTP(S) URL	web_fetch
Discover webpages	web_search
Open/click/find/render a returned turn... reference	matching web_* navigation tool
Discover images	image_search
Retrieve market, weather, sports, or time data	matching *_lookup tool

The default tools are:

Tool	Main input
web_search	queries
web_fetch	pages: [{url, lineno?}]
web_open	search_session_id, pages: [{ref_id, lineno?}]
web_click	search_session_id, links
web_find	search_session_id, matches
web_screenshot	search_session_id, PDF pages
image_search	queries
finance_lookup	instruments
weather_lookup	locations
sports_lookup	lookups
time_lookup	offsets

Search when no exact URL is known:

{
  "queries": [
    {"q": "OpenAI Codex official repository", "domains": ["github.com"]}
  ],
  "response_length": "long"
}

Fetch an explicit URL directly: