miaw-mcp-server by skyrmionz - MCP Server

Salesforce MIAW MCP Server

Connect ChatGPT to your Salesforce Enhanced Chat (MIAW - Messaging for In-App and Web) so your AI assistant can seamlessly hand off conversations to Salesforce agents (both Agentforce bots and human agents).

🎯 What This Does

This MCP (Model Context Protocol) server enables ChatGPT to:

Start messaging sessions with Salesforce agents
Send and receive messages in real-time
Handle transfers between AI chatbots and human agents
Display a live chat widget when transferred to a human agent
End chat sessions properly on both sides
Detect when agents end the chat and notify users
Maintain conversation context throughout the handoff

Perfect for when your ChatGPT assistant needs expert help or encounters questions beyond its scope.

⚡ Quick Start

Prerequisites

Salesforce Org with Enhanced Chat (MIAW) enabled
- Messaging for In-App and Web Channel configured and deployed in Messaging Settings
- Embedded Service Deployment configured and published Make sure it's configured as "Custom Client"
- Omni-channel Routing & Flows configured (Agent - human escalation)
- Agentforce Activated with Outbound Omni-channel Connection configured
- Live Agent Messaging Channel configured
Heroku Account
- Sign up or sign in at heroku.com
- Create an app to host the MCP Server, name it: "miaw-mcp-server"
ChatGPT Plus or Team
- For MCP Connectors: Developer Mode enabled in Settings
- For Custom GPT: Create your own custom GPT
Tools Installed
- Git
- Node.js 18+ (for local testing, optional)

Step 1: Get Salesforce Credentials

You need three pieces of information from your Salesforce org (easiest to find all of this information is at Setup → Embedded Service Deployments → Your Deployment → Install Code Snippet → Chat Code Snippet):

SCRT URL (Salesforce Chat Runtime URL)
- Format: https://your-org-url.my.salesforce-scrt.com
Embedded Service Developer Name
- Example: Target_Messaging_for_In_App_and_Web
Organization ID
- Example: 00DHu000000p8j3R

Step 2: Deploy to Heroku & Clone from Github

Go to the Heroku App you made → "Deploy" tab → Scroll down to "Deploy using Heroku Git" for all commands
In your favorite IDE, Open a New Terminal
Clone the Git repository by typing in: "git clone https://github.com/skyrmionz/miaw-mcp-server.git" and hit Enter
Type in: "heroku login" and hit Enter → Follow the prompts to authenticate
Make sure you're in the correct directory by checking if you're in "miaw-mcp-server", if not type in: "cd miaw-mcp-server" and hit Enter

cd miaw-mcp-server
git init
heroku git:remote -a chatgpt-components
git add .
git commit -am "(enter your comment here)"
git push heroku main

Afterwards, you'll still need to set the Environment Variables in your Heroku App, which you got from earlier:

Go to the Heroku App again → "Settings" tab → Scroll down to "Config Vars" → "Reveal Config Vars" or start adding Environment Variables.
Add these Environment Variables:

Key: MCP_TRANSPORT | Value: http
Key: MIAW_ES_DEVELOPER_NAME | Value: (Your Embedded Service Deployment API Name)
Key: MIAW_ORG_ID | Value: (Your Org ID)
Key: MIAW_SCRT_URL | Value: (Your Org's SCRT URL)

Step 3: Connect to ChatGPT

Deploy to ChatGPT:

Go to ChatGPT → Profile → Settings → Apps & Connectors → Advanced Settings → Developer Mode "On" → Back
Click "Create" in the top right corner
Add an image for the Icon (Optional)
Name your Connector
Add a Description (how/when should ChatGPT use the Connector?)
Enter your Heroku URL to the "MCP Server URL": https://your-app-name.herokuapp.com/mcp
Set Authentication as "No authentication"
Check the "I understand and want to continue..." box
Click the "Create" button
Done! The Connector will be connected to your ChatGPT
Test out the connection!

🚀 How It Works

Conversation Flow

sequenceDiagram
    User->>ChatGPT: "I need help with my order"
    ChatGPT->>MCP Server: generate_guest_access_token()
    MCP Server->>Salesforce: Request access token
    Salesforce-->>MCP Server: Access token
    MCP Server-->>ChatGPT: sessionId
    ChatGPT->>MCP Server: create_conversation(sessionId)
    MCP Server->>Salesforce: Create conversation
    Salesforce-->>MCP Server: conversationId
    ChatGPT->>MCP Server: list_conversation_entries(sessionId, conversationId)
    MCP Server->>Salesforce: Poll for messages (every 500ms, up to 25s)
    Salesforce-->>MCP Server: Chatbot greeting
    MCP Server-->>ChatGPT: "Hi! How can I help?" + _roleInfo.isLiveAgent=false
    ChatGPT->>User: "Hi! How can I help?"
    User->>ChatGPT: "Connect me to a live agent"
    ChatGPT->>MCP Server: send_message(sessionId, conversationId, text)
    MCP Server->>Salesforce: Send message + Route to agent
    ChatGPT->>MCP Server: list_conversation_entries(sessionId, conversationId)
    MCP Server->>Salesforce: Poll for agent response
    Salesforce-->>MCP Server: Live agent greeting + _roleInfo.isLiveAgent=true
    MCP Server-->>ChatGPT: Agent name + isLiveAgent=true
    ChatGPT->>MCP Server: show_salesforce_chat(sessionId, conversationId, agentName)
    MCP Server-->>ChatGPT: Live Chat Widget displayed
    Note over User,ChatGPT: User now chats directly in widget

Live Agent Widget

When a human agent joins the conversation, ChatGPT automatically displays an embedded chat widget:

Real-time messaging - Messages appear instantly
Agent info - Shows agent name and initials
End Chat button - User can end the session
Auto-detection - Knows when agent ends the chat
Styled interface - Professional chat UI that matches ChatGPT

Server-Side Polling

The server intelligently handles polling so ChatGPT doesn't have to:

When list_conversation_entries is called, the server internally polls every 500ms
Waits up to 25 seconds (Heroku's 30s timeout - 5s buffer)
Returns immediately when a non-"Automated Process" message appears
Filters out system messages automatically
ChatGPT receives only the final result

This means ChatGPT always gets timely agent responses without complex polling logic!

🛠️ Local Development

# Install dependencies
npm install

# Set environment variables
cp .env.example .env
# Edit .env with your Salesforce credentials

# Build
npm run build

# Run locally (stdio mode for testing with Claude Desktop)
npm start

# Or run HTTP mode (for testing with curl)
MCP_TRANSPORT=http PORT=3000 node dist/index.js

Testing with cURL

# Health check
curl http://localhost:3000/

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

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

# Call generate_guest_access_token
curl -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc":"2.0",
    "id":3,
    "method":"tools/call",
    "params":{
      "name":"generate_guest_access_token",
      "arguments":{"appName":"Test App","clientVersion":"1.0.0"}
    }
  }'

🐛 Troubleshooting

"Error creating connector" or "Connection closed"

Solution: Make sure your Heroku app is using the /mcp endpoint:

https://your-app-name.herokuapp.com/mcp

"Request failed with status code 400" on token generation

Cause: Invalid Salesforce configuration.

Solution:

Verify MIAW_SCRT_URL is correct (no trailing slash)
Verify MIAW_ES_DEVELOPER_NAME exactly matches Salesforce
Verify MIAW_ORG_ID is your current org ID

"Request failed with status code 401" on conversation creation

Cause: Session expired or invalid.

Solution: Generate a new session with generate_guest_access_token

ChatGPT says "Selena replied: ..." instead of just the message

Cause: Missing instructions in Custom GPT.

Solution: Copy the "CRITICAL MESSAGING RULES" section into your Custom GPT's Instructions field.

Messages arrive late or not at all

Cause: Server-side polling may need adjustment.

Solution: Check Heroku logs:

heroku logs --tail --app your-app-name

Look for "Polling for non-Automated-Process message..." logs.

"Request timeout" (30s+)

Cause: No agent available or very slow response.

Solution:

Ensure agents are online in Salesforce
Check agent capacity settings
Verify routing configuration in Salesforce

End Chat button not working / 404 errors

Cause: Incorrect API endpoint paths.

Solution: The server now uses the correct Salesforce MIAW API endpoints:

DELETE /conversation/{id}/session?esDeveloperName={name} - Ends messaging session
DELETE /conversation/{id}?esDeveloperName={name} - Closes conversation

Make sure your MIAW_ES_DEVELOPER_NAME environment variable is set correctly.

Agent ends chat but widget doesn't update

Cause: Widget not detecting the "agent has ended the chat" message.

Solution: The server now detects messages from "Automated Process" containing:

"agent has ended the chat"
"chat has ended"
"conversation has ended"

The widget will automatically show "The agent has ended this chat session" and disable input.

Live chat widget not appearing

Cause: show_salesforce_chat called too early or isLiveAgent not detected.

Solution:

Check that _roleInfo.isLiveAgent is true before calling show_salesforce_chat
Only call when mostRecentSenderRole is "Agent" (not "Chatbot")

📚 Resources

🤝 Contributing

Contributions welcome! Please:

Fork the repository
Create a feature branch (git checkout -b feature/amazing-feature)
Commit your changes (git commit -m 'Add amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

📄 License

MIT License - see file for details

🙏 Acknowledgments

Built with:

@modelcontextprotocol/sdk
Express.js
Axios
Salesforce Enhanced Chat (MIAW) API

💬 Support

Issues: GitHub Issues
Discussions: GitHub Discussions
Salesforce Help: Trailblazer Community

Made with ❤️ for the Salesforce and AI community