# Grok Search MCP

A local stdio MCP server that exposes xAI-compatible server-side search through a Responses API relay.

## Tools

- `grok_web_search`: public web search with optional allowed or excluded domains.
- `grok_x_search`: X post/profile/thread search. This is deliberately separate and marked high-cost because one request can expand into many metered tool calls.

Both tools report citations, actual upstream tool-call counts, token usage, the effective model, and the relay's raw `cost_in_usd_ticks` value when present.

## Configuration

Required at call time:

```text
BOTCF_API_KEY
```

On Windows, run `npm run setup` for the first-install configuration window. Enter Base URLs, models, and API keys separated by semicolons; the positions are paired, and one model value may be reused for every provider. Public provider settings are stored in `config.json`, while the complete provider array including keys is stored as a current-user DPAPI ciphertext under `%APPDATA%\grok-search-mcp\api-key.dpapi`.

Requests rotate across configured providers. Recoverable network/timeout, authentication, rate-limit, route/model compatibility, and `5xx` failures can switch to the next distinct provider. Each provider is attempted at most once and each MCP call has a hard maximum of three provider attempts. A failover can still duplicate upstream work if a provider accepted a request before its response was lost, so account-side spend limits remain necessary.

For CI or temporary sessions, `GROK_SEARCH_PROVIDERS` may contain a JSON provider array. The legacy `BOTCF_API_KEY`, `BOTCF_BASE_URL`, and `GROK_SEARCH_MODEL` variables remain supported.

Optional:

```text
BOTCF_BASE_URL=https://botcf.com
GROK_SEARCH_MODEL=grok-4.5
```

The server starts and lists tools without a key, then fails closed with a clear error if a tool is called before `BOTCF_API_KEY` is configured. Secrets are never accepted as tool arguments or printed.

Each installation must use its own provider credentials. Do not share `.env` files, DPAPI ciphertext, setup screenshots, or API keys with other users.

## Development

```bash
npm install
npm run check
```

## Codex configuration

After building, register the compiled entry point and forward only the required environment variable:

```toml
[mcp_servers.grok_search]
command = "node"
args = ["D:/path/to/grok-search-mcp/dist/index.js"]
env_vars = ["GROK_SEARCH_PROVIDERS", "BOTCF_API_KEYS", "BOTCF_API_KEY", "GROK_SEARCH_BASE_URLS", "BOTCF_BASE_URL", "GROK_SEARCH_MODELS", "GROK_SEARCH_MODEL"]
startup_timeout_sec = 20
tool_timeout_sec = 180
```

No request is retried automatically. HTTP redirects are rejected so the API key cannot be forwarded to another origin.