Opt-in Baizhi MCP research example: scope before a community adapter

[ct-jaryn]

Problem / motivation

I would like to contribute an optional research integration for users who already have a Baizhi Agent Toolkit account and want its web search and page retrieval tools in DeerFlow. This proposal is intended to improve Baizhi's availability in the ecosystem; it is not a report that DeerFlow's existing MCP support is broken.

DeerFlow already supports HTTP MCP, static headers, request-scoped credentials, tool-name prefixes, and agent tool policies. The Parallel Search example demonstrates the lightest route. I am raising this in Ideas first, as the feature template requests, before implementing a community provider.

Proposed solution

Preferred first contribution: a small, opt-in MCP configuration example and its documentation, using existing DeerFlow behavior:

{
  "mcpServers": {
    "baizhi": {
      "enabled": false,
      "type": "http",
      "url": "https://agent-toolkit.app.baizhi.cloud/mcp",
      "headers": { "Authorization": "$BAIZHI_AUTHORIZATION" },
      "description": "Optional Baizhi Agent Toolkit service; requires your own account and API key."
    }
  }
}

The operator would set BAIZHI_AUTHORIZATION to the complete Bearer <their-key> value in the backend environment. This follows DeerFlow's whole-string environment expansion; Bearer $BAIZHI_API_KEY would not be a valid interpolation example. The entry would stay disabled in the shipped example, and existing search/fetch providers would remain unchanged.

The guide would explain selecting baizhi_websearch_search and baizhi_web_scrape through the existing agent tool policy for a research agent. The service advertises additional tools: connecting it does not itself limit discovery to these two, and routing hints are not an allowlist. I would verify the exact policy recipe against DeerFlow before a PR. Page retrieval can have export options and service-side effects, so this example would not claim that the service is read-only or that an agent allowlist enforces argument-level restrictions.

Only if a native community adapter is useful to maintainers: a separate, optional deerflow.community.baizhi adapter could expose the existing web_search / web_fetch interfaces, following the Serply community contribution. Its additional value would be a deliberately narrow input schema, normalization to DeerFlow's search/fetch result shapes, and enforced download=false for page retrieval. It would call the real MCP tools websearch_search / web_scrape, not invent REST endpoints or replace defaults. Credential, cancellation, timeout and session behavior would reuse existing MCP facilities where possible; any missing abstraction would be discussed separately rather than expanding this submission into an MCP rewrite.

Affected areas

MCP, Config / setup, Docs. Community tools and backend tests only if the adapter route is accepted. No frontend, model provider, default provider, skill or sandbox change is proposed.

Alternatives considered

• Keep the instructions entirely in the Baizhi integration repository: no DeerFlow maintenance cost; appropriate if another named service example does not add enough value here.
• Use generic MCP configuration only: already possible, and the preferred initial route above. A provider wrapper should not duplicate this merely to add a brand name.
• Add a broad built-in provider immediately: deferred until there is agreement that normalized search/fetch interfaces justify the additional maintained code.

Validation and acceptance plan

For a configuration/documentation PR, I would test environment expansion, missing credentials, disabled-by-default behavior, and actual discovery/name-prefix/agent-policy filtering with synthetic transport responses. Credentials must stay out of committed examples and diagnostic output. These checks would distinguish discovered tools from tools made available to the research agent.

If an adapter is accepted, I would add real LangChain dispatch and MCP SDK tests for exact wire names/arguments, schema changes, structured/text responses, malformed and error responses, credential redaction, pagination, timeout, cancellation and session cleanup. The proposed retrieval restriction would be tested at the wire boundary, including attempts to request downloads. No production tools or model calls have been made for this proposal; full application and production acceptance would remain separately identified.

Additional context

Service: Baizhi Agent Toolkit. The public integration repository contains client integration material, not the hosted backend. Users supply their own account/key; queries and page URLs are sent to Baizhi, and calls may consume credits or incur charges. The credential is static Bearer authentication, not OAuth.

I checked existing Issues/PRs and Discussions for baizhi, the endpoint and the Chinese name on 2026-09-21; no matching integration proposal was found. The broad Chinese query returned unrelated agent/citation/skill discussions, which were checked separately.

This proposal was drafted with OpenAI Codex assistance based on the repository's current code and contribution guidance. It does not claim human review of an implementation, a completed integration, or production testing. Any later PR would include DeerFlow's AI disclosure and the required author's own review confirmation.

Would a tested MCP documentation example be useful here, or would maintainers prefer the instructions to remain external? If a community search/fetch adapter is preferred, is the narrow two-tool scope above the appropriate boundary?