MCP Dust Server

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).

Table of Contents

• MCP Dust Server
  • Table of Contents
  • Features
  • Architecture
  • Dust.tt Agentic AI
  • Installation
    • Prerequisites
    • Steps
  • Starting the Server and Client
    • Expected Output
  • API Endpoints
  • Debugging
  • Integration
    • Windsurf IDE Configuration
    • Claude Desktop Integration
  • Testing
  • API Overview
  • Developer Documentation
  • License

Features

• Separate MCP server and test client components
• Interaction with Dust AI agents via the Dust API
• Real-time streaming responses using Server-Sent Events (SSE) and HTTP Stream Transport
• Full JSON-RPC 2.0 support with 'initialize', 'message', 'terminate', and 'run' methods
• Direct tool execution via the 'run' method for simplified client integration
• Robust session management and context preservation
• Secure API key handling with PII masking in logs
• Heartbeat mechanism to maintain persistent connections
• Automatic reconnection for dropped connections
• Comprehensive error handling and reporting
• Support for the latest MCP specification (2025-03-26)
• Status endpoints for monitoring and health checks

Architecture

The MCP Dust Server is built using the following components:

!MCP Server Architecture Diagram

Figure 1: MCP Server Architecture showing the server and client components

1. MCP Server (server.ts):

   • Handles MCP protocol interactions with Dust API
   • Manages session state and context
   • Implements the full MCP lifecycle (initialize, message, terminate)
   • Supports both SSE and HTTP Stream Transport
   • Provides status endpoints for monitoring

2. MCP Test Client (client.ts):

   • Provides a web interface for testing
   • Allows interaction with the MCP server
   • Supports real-time streaming and debugging
   • Includes session management and connection tracking

Dust.tt Agentic AI

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.

!Dust.tt Platform Interface

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

Installation

Prerequisites

• Node.js (recommended: latest LTS version installed via nvm)
• npm (comes with Node.js)
• TypeScript

Steps

1. Clone the repository:

   git clone https://github.com/ma3u/mcp-dust-server.git
   cd mcp-dust-server
   

2. Install dependencies:

   npm install
   

3. Configure 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/Berlin
   

Starting the Server and Client

You can run the MCP server and test client separately or together. The project provides several npm scripts for different scenarios:

1. Start both Server and Client:

   npm run start
   

2. Start MCP Server only:

   npm run start:server
   

3. Start Test Client only:

   npm run start:client
   

Expected Output

If 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_id

For the Test Client:

MCP Test Client running on http://127.0.0.1:6001

---

API Endpoints

The 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 Checks: /health, /ready, /live
• MCP Protocol: /sse (Server-Sent Events), /stream (HTTP Stream Transport)

Debugging

For detailed information about debugging tools and techniques, including the MCP Inspector, please refer to the Developer Documentation.

Troubleshooting Connection Issues

If you're experiencing connection issues with MCP Inspector or other clients, check these common problems:

1. Port Configuration Mismatch: Ensure your .env file has consistent port settings (MCP_PORT, MCP_MIN_PORT, MCP_MAX_PORT)

2. Transport Mode: For Claude Desktop or MCP Inspector with stdio transport, set TRANSPORT_MODE=stdio in your .env

3. 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.

Integration

Windsurf IDE Configuration

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
    }
  }
}

Claude Desktop Integration

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}"
      }
    }
  }
}

Testing

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.

API Overview

The server provides several endpoints for health checks and MCP protocol communication. For detailed API documentation, please refer to the Developer Documentation.

Developer Documentation

For detailed technical information, including project structure, API documentation, debugging tools, and security considerations, please refer to the Developer Documentation.

---

License

This project is licensed under MIT License.