deer-flow/docs/mcp_integrations.md

MCP Integrations (Beta)

This feature is disabled by default. You can enable it by setting the environment variable ENABLE_MCP_SERVER_CONFIGURATION=true.

Warning

Please enable this feature only after securing your front-end and back-end in a managed environment. Otherwise, your system could be compromised.

Enabling MCP

Set the following environment variable in your .env file:

ENABLE_MCP_SERVER_CONFIGURATION=true

Then restart the DeerFlow server.

---

MCP Server Examples

1. GitHub Trending

Fetches trending repositories from GitHub.

{
  "mcpServers": {
    "mcp-github-trending": {
      "transport": "stdio",
      "command": "uvx",
      "args": ["mcp-github-trending"]
    }
  }
}

Available Tools:

• get_github_trending_repositories - Get trending repositories by language and time range

---

2. Filesystem Access

Provides secure file system access with configurable allowed directories.

{
  "mcpServers": {
    "filesystem": {
      "transport": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/path/to/allowed/directory"
      ]
    }
  }
}

Available Tools:

• read_text_file - Read contents of a text file
• read_multiple_files - Read multiple files at once
• write_file - Write content to a file
• edit_file - Edit a file with line-based replacements
• create_directory - Create a new directory
• list_directory - List files and directories
• directory_tree - Get a recursive tree view
• move_file - Move or rename files
• search_files - Search for files by pattern
• get_file_info - Get file metadata

---

3. Brave Search

Web search using Brave Search API.

Prerequisites: Get API key from Brave Search API

{
  "mcpServers": {
    "brave-search": {
      "transport": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-brave-search"],
      "env": {
        "BRAVE_API_KEY": "your-brave-api-key"
      }
    }
  }
}

Available Tools:

• brave_web_search - Perform web searches
• brave_local_search - Search for local businesses and places

---

4. Tavily Search

AI-optimized search engine for research tasks.

Prerequisites: Get API key from Tavily

{
  "mcpServers": {
    "tavily": {
      "transport": "stdio",
      "command": "npx",
      "args": ["-y", "tavily-mcp"],
      "env": {
        "TAVILY_API_KEY": "tvly-your-api-key"
      }
    }
  }
}

Available Tools:

• tavily-search - Perform AI-optimized web search
• tavily-extract - Extract content from web pages

---

Adding MCP Tools to Agents

When using MCP tools in DeerFlow, you need to specify:

1. enabled_tools - Which tools from the MCP server to enable
2. add_to_agents - Which DeerFlow agents can use these tools (researcher, coder, or both)

Example: Full Configuration for Chat API

{
  "messages": [{"role": "user", "content": "Research the top GitHub trends"}],
  "mcp_settings": {
    "servers": {
      "github-trending": {
        "transport": "stdio",
        "command": "uvx",
        "args": ["mcp-github-trending"],
        "enabled_tools": ["get_github_trending_repositories"],
        "add_to_agents": ["researcher"]
      }
    }
  }
}

---

APIs

Get MCP Server Metadata

POST /api/mcp/server/metadata

Use this endpoint to discover available tools from an MCP server.

For stdio type:

{
  "transport": "stdio",
  "command": "npx",
  "args": ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"]
}

For sse type:

{
  "transport": "sse",
  "url": "http://localhost:3000/sse",
  "headers": {
    "Authorization": "Bearer your-token"
  }
}

For streamable_http type:

{
  "transport": "streamable_http",
  "url": "http://localhost:3000/mcp",
  "headers": {
    "API_KEY": "your-api-key"
  }
}

Chat Stream with MCP

POST /api/chat/stream

{
  "messages": [{"role": "user", "content": "Your research query"}],
  "thread_id": "unique-thread-id",
  "mcp_settings": {
    "servers": {
      "your-mcp-server": {
        "transport": "stdio",
        "command": "uvx",
        "args": ["your-mcp-package"],
        "env": {
          "API_KEY": "your-api-key"
        },
        "enabled_tools": ["tool1", "tool2"],
        "add_to_agents": ["researcher"]
      }
    }
  }
}

---

Timeout Configuration

DeerFlow provides configurable timeout settings for MCP server connections to handle various network conditions and server responsiveness scenarios.

Global Default Timeout

Set the default timeout for all MCP server connections via environment variable:

# .env file
MCP_DEFAULT_TIMEOUT_SECONDS=60

Default value: 60 seconds

Per-Request Timeout Override

When querying the MCP server metadata API, you can override the default timeout for a specific request:

Example: Get MCP Server Metadata with Custom Timeout

{
  "transport": "sse",
  "url": "http://localhost:3000/sse",
  "headers": {
    "Authorization": "Bearer your-token"
  },
  "timeout_seconds": 45,
  "sse_read_timeout": 20
}

Parameters:

• timeout_seconds (optional, integer): Overall timeout in seconds for the MCP server connection. Overrides MCP_DEFAULT_TIMEOUT_SECONDS environment variable.
• sse_read_timeout (optional, integer): Timeout in seconds for SSE (Server-Sent Events) streaming read operations. Only applicable for sse transport type. When provided, allows fine-grained control over streaming timeouts.

Timeout Recommendations

• Fast, Local MCP Servers: 10-15 seconds
• Standard Production Servers: 30-60 seconds
• Slow or High-Latency Servers: 60+ seconds (use with caution)

Note

The timeout_seconds parameter is recommended for most use cases. The sse_read_timeout parameter should only be used when you need separate control over SSE streaming read operations.

Example: Chat API with Custom Timeouts

{
  "messages": [{"role": "user", "content": "Research query"}],
  "mcp_settings": {
    "servers": {
      "my-mcp-server": {
        "transport": "sse",
        "url": "http://localhost:3000/sse",
        "timeout_seconds": 45,
        "sse_read_timeout": 20,
        "enabled_tools": ["tool1", "tool2"],
        "add_to_agents": ["researcher"]
      }
    }
  }
}

---

Additional Resources

• MCP Official Documentation
• MCP Server Registry