A Model Context Protocol server that enables interaction with Dust AI agents, allowing integration with development environments like Windsurf IDE and Claude Desktop.
This repository contains an implementation of a Model Context Protocol (MCP) server designed to interact with Dust agents. The server is separated into two main components: the MCP server (which handles Dust API interactions) and the MCP test client (which provides a web interface for testing).
The MCP Dust Server is built using the following components:
Figure 1: MCP Server Architecture showing the server and client components
MCP Server (server.ts):
Handles MCP protocol interactions with Dust API
Provides status endpoints for monitoring
MCP Test Client (client.ts):
Dust.tt is a platform designed to help organizations build and deploy custom AI agents tailored to their specific needs. It integrates advanced AI models, such as GPT-4, Claude, Gemini, and Mistral, with enterprise-grade security features to streamline workflows, automate tasks, and enhance productivity across various business functions.
Figure 2: Screenshot of the Dust.tt platform interface showing agent capabilities
Custom AI Agents: Personalized Agents: Create agents with custom instructions and tools, tailored to team or individual needs.
Company Context: Integrate agents with internal tools like Notion, Slack, GitHub, or external APIs for seamless access to company data.
Multi-Agent Workflows: Combine and chain multiple agents, each with unique capabilities, in a single workflow.
Integration with Data Sources: Data Connections: Connect agents to data from SharePoint, Zendesk, Jira, Salesforce, Snowflake, and more.
Dynamic Querying: Use agents to analyze spreadsheets, databases, and warehouses with natural language or SQL queries.
Real-Time Updates: Sync company knowledge continuously for up-to-date responses.
Open Source: Available on GitHub under the MIT license. With a big community of users and developers.
Hosting: SaaS or own hosting option on your own server
Clone the repository:
git clone https://github.com/ma3u/mcp-dust-server.git
cd mcp-dust-serverInstall dependencies:
npm installConfigure environment variables:
Create a .env file in the root directory based on .env.example:
# Startup Mode (server, client, or both)
START_MODE=both
# MCP Server Configuration
MCP_NAME=Dust MCP Server JS
MCP_HOST=127.0.0.1
MCP_PORT=5001
MCP_TIMEOUT=30 # seconds
# MCP Test Client Configuration
CLIENT_HOST=127.0.0.1
CLIENT_PORT=6001
# Dust API Configuration
DUST_API_KEY=your_dust_api_key_here
DUST_WORKSPACE_ID=your_workspace_id_here
DUST_AGENT_ID=your_agent_id_here
DUST_DOMAIN=https://dust.tt
# User Context Information (used in Dust API requests)
DUST_USERNAME=your_username
[email protected]
DUST_FULLNAME=Your Full Name
DUST_TIMEZONE=Europe/BerlinYou can run the MCP server and test client separately or together. The project provides several npm scripts for different scenarios:
Start both Server and Client:
npm run startStart MCP Server only:
npm run start:serverStart Test Client only:
npm run start:clientIf everything is configured correctly, you should see output similar to:
For the MCP Server:
MCP Server running on http://127.0.0.1:5001 (timeout: 30s)
Server name: Dust MCP Bridge
Dust workspace: your_workspace_id
Dust agent: your_agent_idFor the Test Client:
MCP Test Client running on http://127.0.0.1:6001The server provides several endpoints for health checks and MCP protocol communication. For detailed API documentation, please refer to the Developer Documentation.
Key endpoints include:
/health, /ready, /live/sse (Server-Sent Events), /stream (HTTP Stream Transport)For detailed information about debugging tools and techniques, including the MCP Inspector, please refer to the Developer Documentation.
If you're experiencing connection issues with MCP Inspector or other clients, check these common problems:
Port Configuration Mismatch: Ensure your .env file has consistent port settings (MCP_PORT, MCP_MIN_PORT, MCP_MAX_PORT)
Transport Mode: For Claude Desktop or MCP Inspector with stdio transport, set TRANSPORT_MODE=stdio in your .env
Multiple Response Headers: If you see "ERR_HTTP_HEADERS_SENT" errors, check for middleware sending multiple responses
For a comprehensive troubleshooting guide, see the Troubleshooting Common Issues section in the Developer Documentation.
To integrate the Dust MCP Server with Windsurf IDE, update the configuration file ~/.codeium/windsurf/mcp_config.json:
{
"mcpServers": {
"dust-mcp": {
"command": "npm",
"args": [
"run",
"start:server"
],
"env": {
"DUST_API_KEY": "${YOUR_API_KEY}",
"DUST_WORKSPACE_ID": "${YOUR_WORKSPACE_ID}",
"DUST_AGENT_ID": "${YOUR_AGENT_ID}"
},
"host": "127.0.0.1",
"port": 5001,
"timeout": 30000
}
}
}To integrate the Dust MCP Server with Claude Desktop, update its configuration file:
{
"mcpServers": {
"dust-agent": {
"command": "npm",
"args": [
"run",
"start:server"
],
"cwd": "path/to/mcp-dust-server",
"host": "127.0.0.1",
"port": 5001,
"timeout": 30000,
"env": {
"DUST_API_KEY": "${YOUR_API_KEY}",
"DUST_WORKSPACE_ID": "${YOUR_WORKSPACE_ID}",
"DUST_AGENT_ID": "${YOUR_AGENT_ID}"
}
}
}
}The project includes both web-based and command-line testing tools. For detailed testing information, please refer to the Developer Documentation.
The web-based test client is accessible at http://localhost:6001 when you run the client component, allowing you to interact with your Dust agent and test the MCP server functionality.
The server provides several endpoints for health checks and MCP protocol communication. For detailed API documentation, please refer to the Developer Documentation.
For detailed technical information, including project structure, API documentation, debugging tools, and security considerations, please refer to the Developer Documentation.
This project is licensed under MIT License.