How to Integrate DeerFlow with Other Tools: MCP Servers and Embedded Client Guide

DeerFlow integrates with external tools through an embedded Python client, the Model-Center-Protocol (MCP) server framework, and a dynamic tool registry that hot-reloads configurations without restarting the agent.

DeerFlow is ByteDance's open-source super-agent framework designed for extensibility. Whether you need to embed agent capabilities into existing Python applications or connect to proprietary data warehouses via remote tools, DeerFlow provides multiple integration layers that maintain a consistent high-level API.

Embedded Python Client Integration

The primary integration point for embedding DeerFlow into existing codebases is the DeerFlowClient class located in backend/src/client.py. This client provides a thin wrapper around the full agent harness, exposing chat, streaming, file upload, and skill management APIs.

When you instantiate DeerFlowClient, it lazily creates the underlying LangChain agent only when needed (via _ensure_agent). This design allows you to configure the client upfront without incurring initialization overhead until the first chat() or stream() call.

from src.client import DeerFlowClient

# Create a client with subagent and thinking capabilities enabled

client = DeerFlowClient(subagent_enabled=True, thinking_enabled=True)

# Simple synchronous request

answer = client.chat("Summarize the latest AI research trends.")
print(answer)

# Streaming for real-time UI updates

for event in client.stream("Generate a slide deck about quantum computing."):
    if event.type == "messages-tuple" and event.data["type"] == "ai":
        print(event.data["content"], end="", flush=True)
    elif event.type == "values":
        # Access state snapshots containing artifacts and metadata

        print(f"\nSnapshot: {event.data['title']}")

The client routes all calls through the same middleware stack used by DeerFlow's HTTP gateway, ensuring consistent behavior whether you're using the embedded client or the REST API. Source reference: backend/src/client.py#L65-L115.

Connecting External Tools via MCP

DeerFlow supports the Model-Center-Protocol (MCP) standard for integrating remote tools. The get_mcp_tools function in backend/src/mcp/tools.py dynamically discovers and loads tools from external MCP servers using STDIO, HTTP, or SSE transport protocols.

MCP Server Configuration

External tools are declared in extensions_config.json (or the legacy mcp_config.json). The ExtensionsConfig class in backend/src/config/extensions_config.py parses this file, resolves environment variables, and enables hot-reloading of tool definitions without requiring a server restart.

{
  "mcpServers": {
    "my-warehouse": {
      "enabled": true,
      "type": "http",
      "url": "http://localhost:8080/mcp",
      "headers": {},
      "oauth": {
        "enabled": true,
        "token_url": "https://auth.example.com/oauth/token",
        "client_id": "my-client-id",
        "client_secret": "my-secret"
      },
      "description": "Internal data-warehouse query tool"
    }
  },
  "skills": {}
}

Loading Remote Tools

When get_available_tools is called during agent initialization, it delegates MCP tool discovery to get_mcp_tools (lines 14-64 in backend/src/mcp/tools.py). This function constructs a MultiServerMCPClient that contacts each configured server and retrieves LangChain BaseTool instances. These remote tools become indistinguishable from built-in tools to the agent.

After updating the configuration file, force the client to recognize new tools:

# Reload the agent to pick up new MCP server definitions

client.reset_agent()

# The agent can now access the warehouse query tool

client.chat("List the top-10 customers by revenue this quarter.")

Runtime Tool Registry and Configuration

The get_available_tools function in backend/src/tools/tools.py (lines 22-84) serves as the central registry that assembles the complete tool set for each agent instance. This function merges:

• Built-in tools (e.g., present_file, ask_clarification from backend/src/tools/builtins/)
• Sub-agent tools (when subagent_enabled=True)
• MCP-provided tools (when MCP servers are configured)

The registry reads the latest extensions_config.json via ExtensionsConfig.from_file on every agent creation, enabling runtime changes to tool availability. This architecture allows you to add a new data warehouse query tool to a running system simply by updating the JSON configuration and calling reset_agent(), without restarting the DeerFlow service.

Managing Skills at Runtime

Skills in DeerFlow are markdown bundles loaded from skills/public or skills/custom directories. The DeerFlowClient provides methods to enable or disable specific capabilities dynamically via update_skill, which writes back to extensions_config.json and forces agent reinstantiation.

# List all available skills

print(client.list_skills())

# Disable image generation when not needed

client.update_skill("image-generation", enabled=False)

# Re-enable when required

client.update_skill("image-generation", enabled=True)

Skill management methods are implemented in backend/src/client.py#L140-L185. The SkillsLoader class in backend/src/skills/loader.py handles the filesystem operations for loading these bundles.

File Upload and Document Processing

DeerFlow supports document ingestion through the upload_files method, which automatically converts PDFs and other formats to markdown for agent consumption.

# Upload a document to a specific conversation thread

upload_info = client.upload_files(
    thread_id="proj-123", 
    files=["/path/to/report.pdf"]
)
print(upload_info)

# Reference the uploaded content in subsequent queries

client.chat(
    "Analyze the uploaded report and extract the three most important findings.",
    thread_id="proj-123"
)

The file upload API is implemented in backend/src/client.py#L311-L376. Uploaded documents are converted to markdown and associated with the specified thread ID, making them available as context for that conversation.

Summary

• Embedded Integration: Use DeerFlowClient in backend/src/client.py to embed the super-agent directly into Python applications with lazy agent initialization.
• MCP Protocol: Connect external tools via the Model-Center-Protocol using backend/src/mcp/tools.py and configure servers in extensions_config.json.
• Hot Reloading: Modify tool configurations at runtime through ExtensionsConfig without restarting the DeerFlow service.
• Dynamic Skills: Enable or disable capabilities via update_skill() methods that persist changes to the configuration file.
• Document Pipeline: Upload files through the client API for automatic conversion and thread-associated context management.

Frequently Asked Questions

How do I add a custom tool from my internal API to DeerFlow?

Expose your internal API as an MCP server using the HTTP or SSE transport protocol, then register it in extensions_config.json under the mcpServers key. The get_mcp_tools function in backend/src/mcp/tools.py will automatically discover and load your tool as a LangChain BaseTool instance. After updating the configuration, call client.reset_agent() to make the tool available immediately.

Can I use DeerFlow without the HTTP server?

Yes. The DeerFlowClient class in backend/src/client.py provides a complete embedded interface that operates independently of the HTTP gateway. Import the client directly into your Python scripts or applications, configure it with subagent_enabled and thinking_enabled flags as needed, and use the chat() or stream() methods for local agent execution.

What is the difference between skills and MCP tools?

Skills are markdown-based instruction bundles loaded from the filesystem (skills/public or skills/custom) that modify agent behavior or capabilities, managed through backend/src/skills/loader.py. MCP tools are executable functions hosted on remote servers (or local processes) that perform specific actions like database queries or API calls, loaded via backend/src/mcp/tools.py. Skills configure how the agent thinks; MCP tools extend what the agent can do.

How does DeerFlow handle authentication for external MCP servers?

The ExtensionsConfig system in backend/src/config/extensions_config.py supports OAuth 2.0 authentication for MCP servers. Include an oauth object in your server configuration with token_url, client_id, and client_secret. The backend/src/mcp/oauth.py module handles token acquisition and refresh, passing the authentication headers through the MultiServerMCPClient when connecting to your external tools.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}