feat(tools): web_search MCP tool + mcp_servers harness passthrough

[AbirAbbas]

Summary

Adds a way for harnessed Claude Code agents to invoke web search during a run, so reasoners can look up library docs, error messages, deprecation status, and other context that doesn't live in the codebase.

Three layers, three commits:

1. agentfield.tools.search — vendored multi-provider search package (Jina, Tavily, Firecrawl, Serper) with a unified SearchProvider ABC, env-driven auto-detection, and a priority order overridable via SEARCH_PROVIDER. Ported from Agent-Field/af-deep-research's skills/search from aiohttp to httpx so it lines up with this repo's existing pytest-httpx test infra.

2. mcp_servers parameter on Agent.harness — new keyword arg (also reachable via the router.harness delegation path) that forwards an MCP-server mapping straight to ClaudeAgentOptions.mcp_servers. Honored only by the claude-code provider; opencode/codex/gemini ignore it the same way they already ignore tools=[...].

3. agentfield.tools.web_search.get_web_search_server() — returns (McpSdkServerConfig, [tool_names]) for an in-process MCP server (built via claude_agent_sdk.create_sdk_mcp_server + @tool) that wraps the search package. Reasoners drop the server under a key in mcp_servers={...} and merge the namespaced mcp__af_search__web_search name into their tools=[...] allow-list. Tool description tells the model to reach for it only when the answer can't come from the codebase, mitigating loop risk in coding agents.

Why this shape

Considered building it as a per-call Python pre-step (search before the prompt, inject results) and as a custom-tool registry across providers. Pre-step loses the agent's ability to decide when to search; cross-provider registries would have required modifying three external CLI binaries. The in-process MCP server is the canonical extension point in claude-agent-sdk and matches the way Claude Code itself ships built-in tools — minimal new surface area, no per-call wrapper code in reasoners.

Test plan

• 39 unit/integration tests pass (tests/tools/, tests/test_harness_mcp.py)
  • Per-provider HTTP mocking for Jina, Tavily, Firecrawl, Serper
  • Registry/auto-detect: priority order, SEARCH_PROVIDER override, fallback when preferred is unavailable, custom provider registration
  • web_search wrapper: input validation, no-provider error path, exception-in-search handler, markdown formatting (snippet truncation, missing fields, empty results)
  • Harness plumbing: passthrough to ClaudeAgentOptions, omission when not set, real-server-config wiring, silent ignore on non-claude provider
• 2 live tests in tests/tools/test_search_live_jina.py — skipped without JINA_API_KEY, otherwise hit the real Jina API and assert structured results
• 1 end-to-end test in tests/test_harness_web_search_e2e.py — harness_live marker (deselected by default addopts), gated on both ANTHROPIC_API_KEY and JINA_API_KEY. Drives a real Claude harness call, asks the model to use web_search to look up pytest's docs URL, asserts the model actually invoked the tool

Existing harness suite (130 tests under -k harness): all green, no regressions.

Follow-up

Sister PR coming on Agent-Field/SWE-AF that wires get_web_search_server() into 6 reasoners — run_architect, run_ci_fixer, run_pr_resolver as Tier 1 (web access is high-leverage), and run_coder, run_retry_advisor, run_product_manager as Tier 2 (with prompt guardrails on the coder to scope use). Per-reasoner cost analysis already done; the deterministic / pure-synthesis / short-budget reasoners are deliberately excluded.

🤖 Generated with Claude Code

[github-actions]

Performance

SDK	Memory	Δ	Latency	Δ	Tests	Status
Python	9.4 KB	+4%	0.31 µs	-11%	✓	✓

✓ No regressions detected

[github-actions]

📊 Coverage gate

Thresholds from .coverage-gate.toml: per-surface ≥ 86%, aggregate ≥ 88%, max per-surface regression ≤ 1.0 pp, max aggregate regression ≤ 0.50 pp.

Surface	Current	Baseline	Δ
control-plane	87.40%	87.30%	↑ +0.10 pp	🟡
sdk-go	91.90%	90.70%	↑ +1.20 pp	🟢
sdk-python	93.66%	93.63%	↑ +0.03 pp	🟢
sdk-typescript	92.68%	92.56%	↑ +0.12 pp	🟢
web-ui	89.81%	90.01%	↓ -0.20 pp	🟡
aggregate	88.92%	89.01%	↓ -0.09 pp	🟡

✅ Gate passed

No surface regressed past the allowed threshold and the aggregate stayed above the floor.

[github-actions]

📐 Patch coverage gate

Threshold: 80% on lines this PR touches vs origin/main (from .coverage-gate.toml:thresholds.min_patch).

Surface	Touched lines	Patch coverage	Status
control-plane	0	—	➖ no changes
sdk-go	0	—	➖ no changes
sdk-python	0	—	➖ no changes
sdk-typescript	0	—	➖ no changes
web-ui	0	—	➖ no changes

✅ Patch gate passed

Every surface whose lines were touched by this PR has patch coverage at or above the threshold.

[AbirAbbas]

Closing in favor of a simpler approach.

After research, both providers have native first-party web search built in:

• claude-code: WebSearch / WebFetch are standard Claude Code tool names; just need to be in the harness tools allow-list.
• opencode: websearch / webfetch are built-ins, gated behind OPENCODE_ENABLE_EXA=1 + EXA_API_KEY env vars (Exa backend). The opencode subprocess inherits env naturally via _cli.py's merged_env = {**os.environ}.

So the MCP wrapper, the multi-provider search package, and the mcp_servers harness plumbing were all over-engineered — none of it is needed when the providers already ship their own web search tools. The wiring lives entirely in SWE-AF (and other consumers) by adding tool names to the allow-list and setting the right env vars at deploy time.

Filed as a separate concern: the opencode provider in agentfield silently drops tools=[...] (no permission-config translation). Not blocking web search since opencode enables tools by default, but worth fixing for proper allow-list semantics. Will track separately if it becomes a need.

No production code from this branch was running anywhere — safe to close without follow-up.