MCP Servers

Integrate external tools using the Model Context Protocol

What is MCP?

The Model Context Protocol (MCP) is a standardized way to connect AI agents to external tools and data sources. MCP servers expose tools that DeerFlow can automatically discover and integrate.

Learn more about MCP at modelcontextprotocol.io

MCP Capabilities

File Systems

Access local or remote file systems

Databases

Query PostgreSQL, SQLite, and other databases

External APIs

Integrate GitHub, Brave Search, and more

Browser Automation

Control browsers with Puppeteer

MCP Transport Types

DeerFlow supports three MCP transport mechanisms:

stdio

Standard input/output communication with a subprocess.

Best for: Local command-line tools, Node.js scripts

{
  "type": "stdio",
  "command": "npx",
  "args": ["-y", "@modelcontextprotocol/server-github"],
  "env": {
    "GITHUB_TOKEN": "$GITHUB_TOKEN"
  }
}

SSE (Server-Sent Events)

HTTP-based streaming communication.

Best for: Remote services, cloud-hosted tools

{
  "type": "sse",
  "url": "https://api.example.com/mcp",
  "headers": {
    "Authorization": "Bearer $API_TOKEN"
  }
}

HTTP

Standard HTTP request/response.

Best for: RESTful APIs, stateless services

{
  "type": "http",
  "url": "https://api.example.com/mcp",
  "headers": {
    "X-API-Key": "$API_KEY"
  }
}

Configuration

MCP servers are configured in extensions_config.json (separate from config.yaml).

1. Copy Example Configuration

   cp extensions_config.example.json extensions_config.json
   
2. Configure MCP Servers

   Edit extensions_config.json:

   extensions_config.json

   {
     "mcpServers": {
       "github": {
         "enabled": true,
         "type": "stdio",
         "command": "npx",
         "args": [
           "-y",
           "@modelcontextprotocol/server-github"
         ],
         "env": {
           "GITHUB_TOKEN": "$GITHUB_TOKEN"
         }
       },
       "filesystem": {
         "enabled": true,
         "type": "stdio",
         "command": "npx",
         "args": [
           "-y",
           "@modelcontextprotocol/server-filesystem",
           "/path/to/allowed/directory"
         ]
       },
       "postgres": {
         "enabled": false,
         "type": "stdio",
         "command": "npx",
         "args": [
           "-y",
           "@modelcontextprotocol/server-postgres",
           "postgresql://user:pass@localhost/db"
         ]
       }
     }
   }
   
3. Set Environment Variables

   Set required API tokens in .env:

   .env

   GITHUB_TOKEN=your-github-token
   
4. Restart DeerFlow

   make stop
   make dev
   

   MCP servers are loaded automatically on startup.

OAuth for HTTP/SSE Servers

For HTTP and SSE transport types, DeerFlow supports OAuth token acquisition and automatic refresh.

Supported Grant Types

client_credentials

OAuth 2.0 client credentials flow.

extensions_config.json

{
  "mcpServers": {
    "secure-api": {
      "enabled": true,
      "type": "http",
      "url": "https://api.example.com/mcp",
      "oauth": {
        "enabled": true,
        "token_url": "https://auth.example.com/oauth/token",
        "grant_type": "client_credentials",
        "client_id": "$MCP_CLIENT_ID",
        "client_secret": "$MCP_CLIENT_SECRET",
        "scope": "mcp.read mcp.write"
      }
    }
  }
}

refresh_token

OAuth 2.0 refresh token flow.

extensions_config.json

{
  "mcpServers": {
    "secure-api": {
      "enabled": true,
      "type": "sse",
      "url": "https://api.example.com/mcp",
      "oauth": {
        "enabled": true,
        "token_url": "https://auth.example.com/oauth/token",
        "grant_type": "refresh_token",
        "client_id": "$MCP_CLIENT_ID",
        "client_secret": "$MCP_CLIENT_SECRET",
        "refresh_token": "$MCP_REFRESH_TOKEN",
        "scope": "mcp.read"
      }
    }
  }
}

OAuth Configuration Options

{
  "oauth": {
    "enabled": true,
    "token_url": "https://auth.example.com/oauth/token",
    "grant_type": "client_credentials",  // or "refresh_token"
    "client_id": "$MCP_OAUTH_CLIENT_ID",
    "client_secret": "$MCP_OAUTH_CLIENT_SECRET",
    "scope": "mcp.read mcp.write",
    "refresh_skew_seconds": 60  // Refresh tokens 60s before expiry
  }
}

DeerFlow automatically refreshes tokens before they expire based on refresh_skew_seconds.

Popular MCP Servers

Official MCP Servers

GitHub

Access GitHub repositories, issues, and pull requests.

{
  "github": {
    "enabled": true,
    "type": "stdio",
    "command": "npx",
    "args": ["-y", "@modelcontextprotocol/server-github"],
    "env": {
      "GITHUB_TOKEN": "$GITHUB_TOKEN"
    }
  }
}

Get token: github.com/settings/tokens

Filesystem

Read and write files in allowed directories.

{
  "filesystem": {
    "enabled": true,
    "type": "stdio",
    "command": "npx",
    "args": [
      "-y",
      "@modelcontextprotocol/server-filesystem",
      "/Users/username/Documents",
      "/Users/username/Projects"
    ]
  }
}

Only directories listed in args are accessible. Choose carefully for security.

PostgreSQL

Query PostgreSQL databases.

{
  "postgres": {
    "enabled": true,
    "type": "stdio",
    "command": "npx",
    "args": [
      "-y",
      "@modelcontextprotocol/server-postgres",
      "postgresql://user:password@localhost:5432/database"
    ]
  }
}

Brave Search

Web and local search using Brave.

{
  "brave-search": {
    "enabled": true,
    "type": "stdio",
    "command": "npx",
    "args": ["-y", "@modelcontextprotocol/server-brave-search"],
    "env": {
      "BRAVE_API_KEY": "$BRAVE_API_KEY"
    }
  }
}

Get API key: brave.com/search/api

Puppeteer

Browser automation and web scraping.

{
  "puppeteer": {
    "enabled": true,
    "type": "stdio",
    "command": "npx",
    "args": ["-y", "@modelcontextprotocol/server-puppeteer"]
  }
}

Community MCP Servers

Find more servers in the MCP Servers Directory

Managing MCP Servers

Via API

Manage MCP configuration programmatically:

Get Configuration

curl http://localhost:2026/api/mcp/config

curl -X PUT http://localhost:2026/api/mcp/config \
  -H "Content-Type: application/json" \
  -d @extensions_config.json

curl http://localhost:2026/api/mcp/tools

Dynamic Reloading

DeerFlow automatically detects changes to extensions_config.json:

1. Edit extensions_config.json
2. Save the file
3. MCP manager detects file change
4. New configuration loaded automatically
5. Next agent run uses updated tools

No restart required when modifying extensions_config.json.

Creating Custom MCP Servers

Create your own MCP server:

1. Choose Language/Framework

   MCP servers can be written in any language. Official SDKs:

   • Python: mcp package
   • TypeScript: @modelcontextprotocol/sdk
2. Implement MCP Protocol

   server.ts

   import { Server } from "@modelcontextprotocol/sdk/server/index.js";
   import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
   
   const server = new Server(
     {
       name: "my-custom-server",
       version: "1.0.0",
     },
     {
       capabilities: {
         tools: {},
       },
     }
   );
   
   // Register tools
   server.setRequestHandler("tools/list", async () => {
     return {
       tools: [
         {
           name: "my_tool",
           description: "Does something useful",
           inputSchema: {
             type: "object",
             properties: {
               param: { type: "string" }
             }
           }
         }
       ]
     };
   });
   
   // Handle tool calls
   server.setRequestHandler("tools/call", async (request) => {
     // Implement tool logic
     return { result: "success" };
   });
   
   // Start server
   const transport = new StdioServerTransport();
   await server.connect(transport);
   
3. Package and Publish

   package.json

   {
     "name": "mcp-server-custom",
     "version": "1.0.0",
     "bin": {
       "mcp-server-custom": "./dist/index.js"
     }
   }
   

   Publish to npm or use locally.

4. Configure in DeerFlow

   extensions_config.json

   {
     "mcpServers": {
       "my-custom-server": {
         "enabled": true,
         "type": "stdio",
         "command": "npx",
         "args": ["-y", "mcp-server-custom"]
       }
     }
   }
   

Security Considerations

MCP servers have access to sensitive resources. Configure carefully.

Best Practices

1. Use Environment Variables for Secrets

   "env": {
     "API_KEY": "$MY_API_KEY"  // ✅ From .env
   }
   

   Never hardcode:

   "env": {
     "API_KEY": "sk-12345..."  // ❌ Exposed in config
   }
   

2. Limit Filesystem Access

   [
     "/Users/me/safe-directory"  // ✅ Specific directory
   ]
   

   Avoid:

   [
     "/"  // ❌ Full system access
   ]
   

3. Disable Unused Servers

   {
     "enabled": false  // Disabled servers don't load
   }
   

4. Review Server Code

   • Check source code of community servers
   • Verify npm package authenticity
   • Use official servers when available

Troubleshooting

Server fails to start

Check logs for errors:

tail -f logs/gateway.log

Common issues:

• Missing npm packages: npx will auto-install, but may fail
• Invalid command path
• Missing environment variables
• Permission issues

Tools not appearing

Verify server is enabled:

{
  "enabled": true  // Must be true
}

Check available tools:

curl http://localhost:2026/api/mcp/tools

OAuth authentication fails

Verify:

• Token URL is correct
• Client ID and secret are valid
• Scope is appropriate
• Environment variables are set

Check logs for OAuth errors:

tail -f logs/gateway.log | grep oauth

Server crashes frequently

Add error logging to server code.

Consider using http or sse transport instead of stdio for better error handling.

Wrap server execution in a restart script:

#!/bin/bash
while true; do
  npx -y @modelcontextprotocol/server-custom
  echo "Server crashed, restarting..."
  sleep 5
done

Next Steps

Custom Tools

Learn about creating Python tools

Creating Skills

Build skills that use MCP tools

MCP Specification

Read the official MCP documentation

MCP Servers

Browse community MCP servers