Known Quirks

Documented edge cases, upstream dependencies, and auth traps. File issues for anything not listed here.

Edge cases

Scenario	Affected tools	Expected result
Empty query	Most search tools	`"Query cannot be empty"`
Invalid URL	`fetch_page`	`UnsupportedProtocol` or graceful error
404 / Not Found	`get_github_issue`	Clean `not found` message
Large pages	`fetch_page`	Content truncated with warning
Invalid domain	`search_web(domain=...)`	`No results found`

fetch_page bot detection — uses an auto backend (httpx → falls back to curl with TLS impersonation). If Cloudflare blocks you, pass backend="curl".
search_arxiv maintenance — the arXiv API occasionally returns HTTP 503 during upstream maintenance. Retry after a few minutes.
search_x rate/transport — real-time; subject to X/Twitter rate limits and cookie expiry.

Reddit, Hacker News, LinkedIn, GitHub, and X use a depth parameter balancing latency against enrichment. Result caps roughly:

Tool	quick	default	deep
`search_reddit`	10	25	50
`search_hackernews`	15	30	60
`search_linkedin`	10	25	50
`search_github`	—	30	—
`search_x`	—	30	—

search_web, search_arxiv, search_wikipedia, fetch_page ignore depth.

Symptom	Likely cause	Fix
`search_x` returns 401	Expired X session cookies	Re-extract `auth_token` + `ct0` from x.com, or use `XQUIK_API_KEY`
`search_github` returns empty	Not authenticated	Run `gh auth login` or set `GITHUB_TOKEN`
`get_github_issue` fails	No `gh` CLI / token	Install & auth `gh`, or export `GITHUB_TOKEN`
`search_web`/`fetch_page` weaker results	Exa not configured	Set `EXA_API_KEY` for the semantic fallback (optional)

Env vars must be exported in the same shell where the MCP server runs.