Search Online MCP Server

An MCP (Model Context Protocol) server that exposes a standardized web search tool for agents and clients like OpenAI Codex, Claude, and Cursor. It uses Brave Search under the hood and returns stable, agent‑friendly JSON.

Features

• One tool: search_online (engine: Brave; verticals: web/news/images/videos)

• Stable output shape via structuredContent and a concise text summary

• Fallback chain for robustness:

  1. Fish function search_online (if available)

  2. uvx brave-search-python-client (httpx/psutil)

  3. Direct Brave HTTP API (X-Subscription-Token)

• No stdout leakage: safe JSON‑RPC framing (all debug goes to logs)

Install

cd ~/Projects/mcp
git clone <repo> search-online-mcp
cd search-online-mcp
npm install

Configure Codex

~/.codex/config.toml:

[mcp_servers.searchonline]
command = "node"
args = ["/Users/YOU/Projects/mcp/search-online-mcp/index.mjs"]
env = {
  BRAVE_SEARCH_PYTHON_CLIENT_API_KEY = "YOUR_BRAVE_KEY",
  # skip fish/jq, go straight to uvx for stability
  SEARCH_ONLINE_FORCE_UVX = "1",
}
startup_timeout_ms = 20_000
tool_timeout_sec = 60

Restart Codex. Verify:

codex mcp list
codex mcp get searchonline --json

Optional: install the Fish function directly

If you use fish shell, you can install the search_online function for your own terminal use. It’s the same logic the MCP server’s “fast path” expects.

Dependencies: fish 3+, uvx (from astral-sh/uv), jq, glow (optional), and a Brave API key.

Install:

mkdir -p ~/.config/fish/functions
cp contrib/fish/search_online.fish ~/.config/fish/functions/search_online.fish
set -Ux BRAVE_SEARCH_PYTHON_CLIENT_API_KEY "YOUR_BRAVE_KEY"
# Open a new shell or: source ~/.config/fish/functions/search_online.fish

Usage examples:

# JSON (default)
search_online -L 5 "gaston morixe" | jq '.results[:3] | map({title,url})'

# NDJSON streaming
search_online -o ndjson -L 3 "openai codex" | head -n 3

# Plain text (no color)
search_online -o text -n "rust async tutorial"

# Raw engine JSON
search_online -o raw "openai codex" | jq '.web.results[:2] | map({title,url})'

Notes:

• The function prints a standardized JSON object in -o json mode (engine/vertical/query/results…).

• Set SEARCH_ONLINE_ENGINE to override default engine (currently only brave).

• glow is optional; -n/--no-color disables colorized output.

Tool schema

Input (zod → JSON Schema):

• query string (required) — search query

• vertical enum: web|news|images|videos (default web)

• limit integer 1..20 (optional)

• offset integer ≥0 (optional)

• country, lang, market (optional)

Output:

• content: [ { type: "text", text: "ok results=N" } ]

• structuredContent: full JSON with keys: engine, vertical, query, fetched_at, results[] (rank, title, url, snippet, site_name, etc.)

• on error: isError: true with a text explanation

Environment variables

• BRAVE_SEARCH_PYTHON_CLIENT_API_KEY — Brave API key (required)

• SEARCH_ONLINE_FORCE_UVX=1 — skip fish; go straight to uvx

• SEARCH_ONLINE_DEBUG_STDERR=1 — mirror debug to stderr (Codex logs)

Logs

• MCP server writes to ~/.codex/log/search_online_mcp.log

• Codex session logs:

  • TUI: ~/.codex/log/codex-tui.log

  • exec (non-interactive): stderr you redirect (e.g., --json >out 2>err)

Tests

Local tests (require Brave key unless you mock):

npm run test:all

What they do:

• tests/list_names.mjs: confirms tool names comply with the allowed pattern

• tests/call_basic.mjs: calls search_online (uses structuredContent)

• tests/call_invalid.mjs: confirms missing query produces an MCP error

Troubleshooting

• See ~/.codex/log/search_online_mcp.log for per-call details (PATH, cmd, uvx/http status).

• If you still see “tool call failed” in Codex:

  • Kill stale server: pkill -f "search-online-mcp/index.mjs"

  • Start a new Codex session (not resume)

  • Ensure SEARCH_ONLINE_FORCE_UVX=1

License

MIT