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

> Learn how to integrate DeerFlow with other tools using its embedded Python client and MCP server framework. Effortlessly connect and hot-reload configurations without service restarts.

- Repository: [Bytedance Inc./deer-flow](https://github.com/bytedance/deer-flow)
- Tags: how-to-guide
- Published: 2026-03-08

---

**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`](https://github.com/bytedance/deer-flow/blob/main/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.

```python
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`](https://github.com/bytedance/deer-flow/blob/main/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`](https://github.com/bytedance/deer-flow/blob/main/extensions_config.json) (or the legacy [`mcp_config.json`](https://github.com/bytedance/deer-flow/blob/main/mcp_config.json)). The `ExtensionsConfig` class in [`backend/src/config/extensions_config.py`](https://github.com/bytedance/deer-flow/blob/main/backend/src/config/extensions_config.py) parses this file, resolves environment variables, and enables hot-reloading of tool definitions without requiring a server restart.

```json
{
  "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`](https://github.com/bytedance/deer-flow/blob/main/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:

```python

# 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`](https://github.com/bytedance/deer-flow/blob/main/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`](https://github.com/bytedance/deer-flow/blob/main/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`](https://github.com/bytedance/deer-flow/blob/main/extensions_config.json) and forces agent reinstantiation.

```python

# 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`](https://github.com/bytedance/deer-flow/blob/main/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.

```python

# 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`](https://github.com/bytedance/deer-flow/blob/main/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`](https://github.com/bytedance/deer-flow/blob/main/backend/src/mcp/tools.py) and configure servers in [`extensions_config.json`](https://github.com/bytedance/deer-flow/blob/main/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`](https://github.com/bytedance/deer-flow/blob/main/extensions_config.json) under the `mcpServers` key. The `get_mcp_tools` function in [`backend/src/mcp/tools.py`](https://github.com/bytedance/deer-flow/blob/main/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`](https://github.com/bytedance/deer-flow/blob/main/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`](https://github.com/bytedance/deer-flow/blob/main/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`](https://github.com/bytedance/deer-flow/blob/main/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`](https://github.com/bytedance/deer-flow/blob/main/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`](https://github.com/bytedance/deer-flow/blob/main/backend/src/mcp/oauth.py) module handles token acquisition and refresh, passing the authentication headers through the `MultiServerMCPClient` when connecting to your external tools.