Package Exports

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (@mseep/mcp-dust-server) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

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

MCP Dust Server

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

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

Clone the repository:

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

Install dependencies:
```
npm install
```

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
DUST_EMAIL=your_email@example.com
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:

Start both Server and Client:
```
npm run start
```
Start MCP Server only:
```
npm run start:server
```
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:

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.

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