Dust MCP Server

🚀 A TypeScript-based MCP (Model Context Protocol) Server with advanced agent conversation features.

GitHub Repository: dust-mcp-server-postman-railway

Table of Contents

• User Manual
  • Features
  • Getting Started
  • Quick Start
  • Configuration
  • Troubleshooting
• Developer Manual
  • Architecture
  • Agent Conversation Flow
  • API Documentation
  • Development Setup
  • Testing
  • Deployment

User Manual

Features

• ✅ TypeScript-powered MCP server
• 🏗️ Modern ES2022+ JavaScript features
• 🔍 Built-in API documentation
• 🧪 Comprehensive test suite with Jest
• 🛠️ Developer-friendly tooling
• 🔄 Hot-reloading development server
• 📦 Module aliases for clean imports
• 🔒 Environment-based configuration
• 🧩 Extensible architecture

🚀 Getting Started

⚙️ Prerequisites

Before you begin, ensure you have the following installed:

• Node.js (v18+ required, v20+ recommended)
• npm (included with Node.js)
• TypeScript (included as a dev dependency)
• Git (for version control)

🛠️ Installation

1. Clone the repository

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

2. Install dependencies

   npm install
   

3. Set up environment variables

   Create a .env file in the root directory with the following variables:

   PORT=3000
   NODE_ENV=development
   DEFAULT_WORKSPACE_ID=default
   WORKSPACE_DEFAULT_API_KEY=your_api_key_here
   WORKSPACE_DEFAULT_NAME=Default Workspace
   

🏗️ Development

1. Start the development server

   npm run dev
   

   This will start the server with hot-reloading enabled.

2. Build for production

   npm run build
   npm start
   

3. Run tests

   npm test        # Run all tests
   npm run test:watch  # Run tests in watch mode
   npm run test:coverage  # Generate test coverage report
   

4. Linting and Formatting

   npm run lint     # Check for linting errors
   npm run lint:fix # Automatically fix linting issues
   npm run format   # Format code using Prettier
   

Developer Manual

Architecture

[Architecture overview]

Agent Conversation Flow

The following diagram illustrates the conversation flow between MCP Client, MCP Server, and Dust with session management:

sequenceDiagram
    participant User
    participant MCPClient as MCP Client
    participant MCPServer as MCP Server
    participant SessionMgr as Session Manager
    participant ConvMgr as Conversation Manager
    participant Dust as Dust Service

    %% Session Initialization
    User->>MCPClient: Start New Session
    MCPClient->>MCPServer: POST /api/sessions
    MCPServer->>SessionMgr: createSession()
    SessionMgr-->>MCPServer: {sessionId, status: 'active'}
    MCPServer->>ConvMgr: new Conversation(sessionId)
    ConvMgr-->>MCPServer: {conversationId, state: 'initializing'}
    MCPServer-->>MCPClient: {sessionId, conversationId, status: 'active'}
    MCPClient-->>User: Session Ready

    %% Message Flow
    loop While Session Active
        User->>MCPClient: Send Message
        MCPClient->>MCPServer: POST /api/conversations/{conversationId}/messages
        MCPServer->>ConvMgr: processMessage(message)
        alt Has Files
            ConvMgr->>FileUploadHandler: handleUpload(files)
            FileUploadHandler-->>ConvMgr: {fileIds, paths}
        end
        ConvMgr->>Dust: forwardMessage(conversationId, message, files)
        Dust-->>ConvMgr: {response, metadata}
        ConvMgr->>ConversationHistory: addMessage(message, response)
        MCPServer-->>MCPClient: {response, state, metadata}
        MCPClient-->>User: Display Response
        
        %% Timeout Handling
        alt Idle Timeout Reached
            ConvMgr->>ConvMgr: handleIdleTimeout()
            ConvMgr->>SessionMgr: updateSession(sessionId, {state: 'idle'})
            SessionMgr-->>ConvMgr: {status: 'updated'}
            ConvMgr-->>MCPServer: {event: 'stateChange', state: 'idle'}
            MCPServer-->>MCPClient: {event: 'sessionIdle'}
        end
    end

    %% Session Termination
    User->>MCPClient: End Session
    MCPClient->>MCPServer: DELETE /api/sessions/{sessionId}
    MCPServer->>SessionMgr: deleteSession(sessionId)
    SessionMgr->>ConvMgr: destroy()
    ConvMgr->>ConversationHistory: clear()
    ConvMgr-->>SessionMgr: {status: 'destroyed'}
    SessionMgr-->>MCPServer: {status: 'deleted'}
    MCPServer-->>MCPClient: {status: 'session_ended'}
    MCPClient-->>User: Session Ended

API Documentation

The following API endpoints are available in the application:

Health Check

GET /health

Check if the server is running.

Response:

{
  "status": "ok"
}

Workspace Agent Configurations

GET /api/workspaces/:workspaceId/agents

Get all agent configurations for a workspace.

Parameters:

• workspaceId (path, required): The ID of the workspace
• forceRefresh (query, optional): Force refresh the agent configurations (true/false)

Response:

{
  "agents": [
    {
      "id": "agent1",
      "name": "Agent One",
      "description": "First agent",
      "config": {}
    }
  ]
}

Get Specific Agent

GET /api/workspaces/:workspaceId/agents/:agentId

Get configuration for a specific agent.

Parameters:

• workspaceId (path, required): The ID of the workspace
• agentId (path, required): The ID of the agent

Response:

{
  "id": "agent1",
  "name": "Agent One",
  "description": "First agent",
  "config": {}
}

🛠 Environment Variables

The application uses the following environment variables:

Variable	Required	Default	Description
PORT	No	3000	Port to run the server on
NODE_ENV	No	development	Application environment
DEFAULT_WORKSPACE_ID	No	default	Default workspace ID
WORKSPACE_<ID>_API_KEY	Yes	-	API key for the workspace
WORKSPACE_<ID>_NAME	No	Workspace ID	Display name for the workspace

🤝 Contributing

Contributions are welcome! Please follow these steps:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/AmazingFeature)
3. Commit your changes (git commit -m 'Add some AmazingFeature')
4. Push to the branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

📝 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

• Built with TypeScript and Node.js
• Uses Express for the web server
• Implements the Model Context Protocol (MCP) specification

📡 JSON-RPC Interface

The server supports the Model Context Protocol (MCP) via JSON-RPC 2.0 over HTTP.

Discovering Available Tools

To list all available tools, send a mcp_discover request:

curl -X POST http://localhost:3000 \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "mcp_discover",
    "params": {}
  }'

Calling a Tool

To call a specific tool, such as list_assistants:

curl -X POST http://localhost:3000 \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 2,
    "method": "list_assistants",
    "params": {}
  }'

Prerequisites

Ensure you have curl installed. For testing with netcat (nc), install it using:

• macOS: brew install netcat
• Ubuntu/Debian: sudo apt-get install netcat

🔐 Tool Environment Variables

This project uses a .env file to manage environment-specific variables, such as API keys. To get started:

1. Create your environment file: Copy the example environment file to a new file named .env:

   cp .env.example .env
   

2. Update API Keys: Open the newly created .env file. You'll see placeholder environment variables for the Dust API:

   DUST_API_KEY=
   DUST_WORKSPACE_ID=
   DUST_AGENT_ID=
   

   Update these lines with your actual Dust API Key, Workspace ID, and Agent ID. These environment variables are used by the tools to interact with the Dust API. You can inspect the files in the tools directory to see how they are used.

// environment variables are used inside of each tool file
const apiKey = process.env.DUST_API_KEY;
const workspaceId = process.env.DUST_WORKSPACE_ID;
// etc.

Note: The generated tools will need to be configured to use these specific environment variables (DUST_API_KEY, DUST_WORKSPACE_ID, DUST_AGENT_ID). If the tools were generated for a different API or expect different environment variable names, you will need to manually update the JavaScript files in the tools/ directory to use these variables correctly for authentication and API calls.

Testing with Postman

Postman provides a user-friendly interface to test your MCP server. Follow these steps to get started:

Prerequisites for Postman

• Install the latest Postman Desktop Application
• Node.js v18+ installed
• Your MCP server project dependencies installed (npm install)

Creating a New MCP Request

1. Open Postman
2. Click "New" > "MCP Request"
3. In the new tab, you'll see the MCP request configuration

Configuring the MCP Server

1. Set the request type to STDIO

2. In the command field, enter the full path to Node.js followed by the full path to mcpServer.js:

   /Users/ma3u/.nvm/versions/node/v22.14.0/bin/node /Users/ma3u/projects/postman-dust-mcp-server/mcpServer.js
   

   To find these paths on your system:

Get Node.js path

which node

Get absolute path to mcpServer.js (run from your project directory)

pwd

Then append "/mcpServer.js" to the output

## Starting the Server

1. Click the "Connect" button in Postman
2. You should see the server start up in the terminal at the bottom of the screen
3. Once connected, you'll see a list of available tools in the response section

## Testing Tools

1. In the request body, enter a JSON-RPC request. For example, to list assistants:

   ```json
   {
     "jsonrpc": "2.0",
     "id": 1,
     "method": "list_assistants",
     "params": {}
   }

2. Click "Send" to execute the request
3. View the response in the lower panel

Available Tools

You can call any of the following tools directly by name in the method field:

• list_workspace_vaults - List all workspace vaults
• list_assistants - List available assistants
• list_data_source_views - List data source views
• get_conversation_events - Get conversation events
• get_data_sources - Get available data sources
• search_assistants_by_name - Search for assistants by name
• get_conversation - Get conversation details
• retrieve_document - Retrieve a document
• get_app_run - Get application run details
• get_events_for_message - Get events for a specific message
• upsert_document - Create or update a document
• get_documents - Get multiple documents
• create_conversation - Start a new conversation
• create_message - Send a message
• create_content_fragment - Create a content fragment
• create_app_run - Start a new application run
• search_data_source - Search within a data source
• search_data_source_view - Search within a data source view

Troubleshooting

Common Issues and Solutions

1. Server Not Starting

   • Verify Node.js is installed and in your PATH
   • Check that all dependencies are installed (npm install)
   • Look for error messages in the Postman Notifications tab

2. Connection Timeouts

   • Ensure the server is running before making requests
   • Try restarting the server if it becomes unresponsive
   • Check that no other process is using the required port

3. Invalid Method Errors

   • Use tool names exactly as listed in the "Available Tools" section
   • Don't add prefixes like mcp. or rpc. to method names
   • Ensure the params field is an empty object {}

4. Environment Variables

   • Verify .env file exists and contains required variables
   • Ensure environment variables are properly loaded
   • Check for typos in variable names

5. Server Logs

   • Check the Postman Notifications tab for server output
   • Look for error messages or stack traces
   • The server logs all incoming requests and errors

Restarting the Server

If you encounter issues, try these steps:

1. Click the "Disconnect" button in Postman
2. Wait a few seconds
3. Click "Connect" to restart the server
4. Try your request again

Node Version Issues

• Make sure you're using Node.js v18 or higher
• You can specify the full path to a specific Node.js version if needed
• If using nvm, ensure you're using the correct Node.js version:

  nvm use 18  # or your preferred version
  

Tool Execution Errors

• Check the Postman console for detailed error messages
• Verify that all required parameters are included in your request

Example: Listing Data Sources

Here's how to list all data sources:

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "list_data_sources",
  "params": {}
}

Next Steps

Once you've verified the server works in Postman, you can integrate it with other MCP clients like Claude Desktop.

realpath mcpServer.js

Use the node command followed by the full path to mcpServer.js as the command for your new Postman MCP Request. Then click the Connect button. You should see a list of tools that you selected before generating the server. You can test that each tool works here before connecting the MCP server to an LLM.

👩‍💻 Connect the MCP Server to Claude

You can connect your MCP server to any MCP client. Here we provide instructions for connecting it to Claude Desktop.

Step 1: Note the full path to node and the mcpServer.js from the previous step.

Step 2. Open Claude Desktop → Settings → Developers → Edit Config and add a new MCP server:

{
  "mcpServers": {
    "<server_name>": {
      "command": "<absolute/path/to/node>",
      "args": ["<absolute/path/to/mcpServer.js>"]
    }
  }
}

Restart Claude Desktop to activate this change. Make sure the new MCP is turned on and has a green circle next to it. If so, you're ready to begin a chat session that can use the tools you've connected.

Warning: If you don't supply an absolute path to a node version that is v18+, Claude (and other MCP clients) may fall back to another node version on the system of a previous version. In this case, the fetch API won't be present and tool calls will not work. If that happens, you can a) install a newer version of node and point to it in the command, or b) import node-fetch into each tool as fetch, making sure to also add the node-fetch dependency to your package.json.

Additional Options

🐳 Docker Deployment (Production)

For production deployments, you can use Docker:

1. Build Docker image

docker build -t <your_server_name> .

2. Claude Desktop Integration

Add Docker server configuration to Claude Desktop (Settings → Developers → Edit Config):

{
  "mcpServers": {
    "<your_server_name>": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "--env-file=.env", "<your_server_name>"]
    }
  }
}

Add your environment variables (API keys, etc.) inside the .env file.

The project comes bundled with the following minimal Docker setup:

FROM node:22.12-alpine AS builder

WORKDIR /app
COPY package.json package-lock.json ./
RUN npm install

COPY . .

ENTRYPOINT ["node", "mcpServer.js"]

🌐 Server-Sent Events (SSE)

To run the server with Server-Sent Events (SSE) support, use the --sse flag:

node mcpServer.js --sse

🛠️ Additional CLI commands

List tools

List descriptions and parameters from all generated tools with:

node index.js tools

Example:

Available Tools:

Workspace: acme-workspace
  Collection: useful-api
    list_all_customers
      Description: Retrieve a list of useful things.
      Parameters:
        - magic: The required magic power
        - limit: Number of results returned
        [...additional parameters...]

➕ Adding New Tools

Extend your MCP server with more tools easily:

1. Visit Postman MCP Generator.
2. Pick new API request(s), generate a new MCP server, and download it.
3. Copy new generated tool(s) into your existing project's tools/ folder.
4. Update your tools/paths.js file to include new tool references.

💬 Questions & Support

Visit the Postman MCP Generator page for updates and new capabilities.

Join the #mcp-lab channel in the Postman Discord to share what you've built and get help.