Postman MCP Generator

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

Before you begin, ensure you have the following installed:

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

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

This will start the server with hot-reloading enabled.

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

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

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

The following API endpoints are available in the application:

Get all agent configurations for a workspace.

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

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

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

To list all available tools, send amcp_discoverrequest:

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

To call a specific tool, such aslist_assistants:

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

Ensure you havecurlinstalled. For testing withnetcat(nc), install it using:

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

This project uses a.envfile 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:

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 thetoolsdirectory 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 thetools/directory to use these variables correctly for authentication and API calls.

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

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

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

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

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: 

- Click "Send" to execute the request
- View the response in the lower panel
You can call any of the following tools directly by name in themethodfield:
- 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
- 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
- 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
- Use tool names exactly as listed in the "Available Tools" section

- Don't add prefixes likemcp.orrpc.to method names

- Ensure theparamsfield is an empty object{}
- Verify.envfile exists and contains required variables

- Ensure environment variables are properly loaded

- Check for typos in variable names
- Check the Postman Notifications tab for server output

- Look for error messages or stack traces

- The server logs all incoming requests and errors
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
- 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:

- Check the Postman console for detailed error messages

- Verify that all required parameters are included in your request

Here's how to list all data sources:

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

Use the node command followed by the full path tomcpServer.jsas the command for your new Postman MCP Request. Then click theConnectbutton. 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.
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 themcpServer.jsfrom the previous step.
Step 2. Open Claude Desktop →Settings→Developers→Edit Configand add a new MCP server: