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
- ✅ 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
-
Clone the repository
git clone https://github.com/ma3u/dust-mcp-server-postman-railway.git cd dust-mcp-server-postman-railway -
Install dependencies
npm install -
Set up environment variables
Create a
.envfile 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
-
Start the development server
npm run devThis will start the server with hot-reloading enabled.
-
Build for production
npm run build npm start -
Run tests
npm test # Run all tests npm run test:watch # Run tests in watch mode npm run test:coverage # Generate test coverage report -
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 workspaceforceRefresh(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 workspaceagentId(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:
- Fork the repository
- Create a feature branch (
git checkout -b feature/AmazingFeature) - Commit your changes (
git commit -m 'Add some AmazingFeature') - Push to the branch (
git push origin feature/AmazingFeature) - 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:
-
Create your environment file: Copy the example environment file to a new file named
.env:cp .env.example .env -
Update API Keys: Open the newly created
.envfile. 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
toolsdirectory 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
- Open Postman
- Click "New" > "MCP Request"
- In the new tab, you'll see the MCP request configuration
Configuring the MCP Server
-
Set the request type to
STDIO -
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.jsTo 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": {}
}
- Click "Send" to execute the request
- 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 vaultslist_assistants- List available assistantslist_data_source_views- List data source viewsget_conversation_events- Get conversation eventsget_data_sources- Get available data sourcessearch_assistants_by_name- Search for assistants by nameget_conversation- Get conversation detailsretrieve_document- Retrieve a documentget_app_run- Get application run detailsget_events_for_message- Get events for a specific messageupsert_document- Create or update a documentget_documents- Get multiple documentscreate_conversation- Start a new conversationcreate_message- Send a messagecreate_content_fragment- Create a content fragmentcreate_app_run- Start a new application runsearch_data_source- Search within a data sourcesearch_data_source_view- Search within a data source view
Troubleshooting
Common Issues and Solutions
-
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
-
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
-
Invalid Method Errors
- Use tool names exactly as listed in the "Available Tools" section
- Don't add prefixes like
mcp.orrpc.to method names - Ensure the
paramsfield is an empty object{}
-
Environment Variables
- Verify
.envfile exists and contains required variables - Ensure environment variables are properly loaded
- Check for typos in variable names
- Verify
-
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:
- Click the "Disconnect" button in Postman
- Wait a few seconds
- Click "Connect" to restart the server
- 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
.envfile.
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:
- Visit Postman MCP Generator.
- Pick new API request(s), generate a new MCP server, and download it.
- Copy new generated tool(s) into your existing project's
tools/folder. - Update your
tools/paths.jsfile 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.