cxws-mcp

cxws-mcp exposes the Codex standalone cloud-search endpoint as one MCP tool, web_run. 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

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 Contract

web_run accepts the standalone search operations at the top level:

• search_query, image_query
• open, click, find, screenshot
• finance, weather, sports, time
• response_length: short, medium, or long
• optional context
• optional search_session_id

Start a search without search_session_id:

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

Every successful result begins with a model-visible line and also returns structured content:

search_session_id: ws_550e8400-e29b-41d4-a716-446655440000

<search output>

{
  "search_session_id": "ws_550e8400-e29b-41d4-a716-446655440000",
  "output": "<search output>",
  "results": [],
  "results_omitted": false
}

Reuse that exact ID when open, click, find, or screenshot refers to a previous turn... result. Dependent navigation calls should be sequential. Literal HTTP(S) URLs can be opened or searched without an existing session.

Limits

• four search_query entries; four require medium or long output
• 16 operations per call
• 20 domains per query
• 8 KiB per text operand and 64 KiB of