Respond.io MCP Server

A Model Context Protocol (MCP) server implementation for the Respond.io API, enabling seamless integration with AI assistants, automation tools, and Claude Desktop.

Features

Contact Management

✅ Get, create, update, and delete contacts
✅ Create or update contact (upsert by identifier)
✅ Merge two contacts (primary + secondary)
✅ List contacts with filters and search
✅ Add and remove contact tags
✅ Update contact lifecycle stages
✅ List contact channels (e.g. WhatsApp, Facebook)

Messaging

✅ Send messages (text, attachments, WhatsApp templates, emails)
✅ Retrieve message details and status
✅ List messages for a contact (with pagination)
✅ Support for multiple channel types

Conversations

✅ Assign/unassign conversations to users
✅ Open and close conversations
✅ Add closing notes and summaries

Workspace Management

✅ List users and get user by ID
✅ List, get, and create custom fields
✅ List channels and message templates (e.g. WhatsApp)
✅ List closing notes (for closing conversations)
✅ Create, update, and delete workspace tags

Comments

✅ Add internal comments to contacts
✅ Mention users in comments

HTTP/STDIO Dual Mode

✅ Can run as a local subprocess via stdio or as an HTTP server (/mcp endpoint)
✅ Health endpoint (/health) for monitoring and uptime checks
✅ CORS enabled for HTTP mode

Prerequisites

Node.js 18+
npm / yarn / bun
Git

Installation

# Clone the repository
git clone https://github.com/respond-io/mcp-server.git
cd mcp-server

# Install dependencies (includes Respond.io SDK)
npm install

# Build the project
npm run build

The project depends on @respond-io/typescript-sdk. See SETUP_GUIDE.md for full installation and configuration.

Configuration

Environment Variables

The server is configured using environment variables. Set them in your shell or deployment environment.

RESPONDIO_API_KEY: (Required) Your Respond.io API key.
RESPONDIO_BASE_URL: The base URL for the Respond.io API (defaults to https://api.respond.io/v2).
MCP_SERVER_MODE: The server mode, either stdio or http (defaults to stdio).
PORT: The port for HTTP mode (defaults to 3000).

Usage with Claude Desktop

You can use this server with Claude Desktop in either STDIO (local subprocess) or HTTP (hosted or local HTTP server) mode.

1️⃣ STDIO Mode (Recommended for local Claude Desktop)

Configure Claude Desktop (For Development Purpose):

{
      "command": "node",
      "args": [
        "/<Your Local Folder Path>/dist/index.js"
      ],
      "env": {
        "RESPONDIO_API_KEY": "your_api_key",
        "MCP_SERVER_MODE": "stdio"
      }
    }

Configure Claude Desktop (For Production Usage):

{
      "command": "npx",
      "args": [
        "@respond-io/mcp-server"
      ],
      "env": {
        "RESPONDIO_API_KEY": "your_api_key",
        "MCP_SERVER_MODE": "stdio"
      }
    }

Launch Claude Desktop and add this MCP server.
The server will start as a subprocess and communicate over stdio.

Test: Try any MCP tool from Claude Desktop, e.g., get a contact or send a message.

2️⃣ HTTP Mode (For remote/hosted or local HTTP integration)

Start the server in HTTP mode:

npm run start:http

or (if built):

export MCP_SERVER_MODE=http
node dist/index.js

Configure Claude Desktop:

{
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "http://localhost:3000/mcp",
        "--header",
        "Authorization:${AUTH_HEADER}"
      ],
      "env": {
        "AUTH_HEADER": "Bearer your-token-here"
      }
    }

Test HTTP health:

curl http://localhost:3000/health
# {"status":"ok"}

Test HTTP MCP endpoint:

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

You should get a JSON list of available tools.

Usage Examples

Contact Management

Get a Contact

get_contact({ identifier: "id:12345" })
get_contact({ identifier: "email:user@example.com" })
get_contact({ identifier: "phone:+60123456789" })

Create a Contact

create_contact({
  identifier: "phone:+60123456789",
  firstName: "John",
  lastName: "Doe",
  email: "john.doe@example.com",
  language: "en",
  custom_fields: [
    { name: "Company", value: "Acme Corp" },
    { name: "Order Number", value: 12345 }
  ]
})

List Contacts with Filters

list_contacts({
  limit: 50,
  search: "john@example.com",
  timezone: "Asia/Kuala_Lumpur"
})

Add Tags

add_contact_tags({
  identifier: "id:12345",
  tags: ["vip", "premium", "sales"]
})

Create or Update Contact (upsert)

create_or_update_contact({
  identifier: "email:user@example.com",
  firstName: "John",
  lastName: "Doe",
  email: "user@example.com"
})

Merge Contacts

merge_contacts({
  primaryContactId: 1,
  secondaryContactId: 2,
  firstName: "Merged Name"
})

List Contact Channels

list_contact_channels({ identifier: "id:12345", limit: 10 })

Update Contact Lifecycle

update_contact_lifecycle({ identifier: "id:12345", stage: "Lead" })
// Clear lifecycle: stage: null

Messaging

Send Text Message

send_message({
  identifier: "id:12345",
  channelId: null, // Use last interacted channel
  messageType: "text",
  text: "Hello! Thank you for contacting us."
})

Send WhatsApp Template

send_message({
  identifier: "phone:+60123456789",
  channelId: 5678,
  messageType: "whatsapp_template",
  templateName: "order_confirmation",
  templateLanguage: "en"
})

Send Email

send_message({
  identifier: "email:user@example.com",
  channelId: 1234,
  messageType: "email",
  text: "Your order has been shipped!",
  subject: "Order Shipment Notification"
})

Send Attachment

send_message({
  identifier: "id:12345",
  channelId: 5678,
  messageType: "attachment",
  attachmentUrl: "https://example.com/invoice.pdf",
  attachmentType: "file"
})

Get Message

get_message({ identifier: "id:12345", messageId: 987654 })

List Messages

list_messages({
  identifier: "id:12345",
  limit: 20,
  cursorId: undefined  // optional, for pagination
})

Conversations

Assign Conversation

assign_conversation({
  identifier: "id:12345",
  assignee: "123"
})
assign_conversation({
  identifier: "id:12345",
  assignee: "agent@example.com"
})
assign_conversation({
  identifier: "id:12345",
  assignee: "null"
})

Close Conversation

update_conversation_status({
  identifier: "id:12345",
  status: "close",
  category: "Resolved",
  summary: "Customer issue resolved successfully"
})

Comments

Add Comment

create_comment({
  identifier: "id:12345",
  text: "Customer requested a callback tomorrow at 2 PM"
})
// Mention a user
create_comment({
  identifier: "id:12345",
  text: "{{@user.456}} please follow up with this customer"
})

Workspace Management

List Users

list_users({ limit: 20 })

Get User

get_user({ id: 123 })

List Custom Fields

list_custom_fields({ limit: 10 })

Get Custom Field

get_custom_field({ id: 1 })

Create Custom Field

create_custom_field({
  name: "Customer Tier",
  slug: "customer_tier",
  description: "Customer membership tier",
  dataType: "list",
  allowedValues: ["Bronze", "Silver", "Gold", "Platinum"]
})

List Channels

list_channels({ limit: 10 })

List Closing Notes

list_closing_notes({ limit: 10 })

List Message Templates (e.g. WhatsApp)

list_templates({ channelId: 5678, limit: 10 })

Create Tag

create_tag({
  name: "VIP",
  description: "VIP customers",
  colorCode: "#FF5733"
})

Update Tag

update_tag({
  currentName: "VIP",
  name: "Premium",
  colorCode: "#FFD700"
})

Delete Tag

delete_tag({ name: "Old Tag" })

Available Tools

The server exposes 28 MCP tools for contacts, messaging, conversations, comments, and workspace management.

Summary:

Contact (11): get_contact, create_contact, update_contact, delete_contact, list_contacts, add_contact_tags, remove_contact_tags, create_or_update_contact, merge_contacts, list_contact_channels, update_contact_lifecycle
Messaging (3): send_message, get_message, list_messages
Conversation (2): assign_conversation, update_conversation_status
Comment (1): create_comment
Workspace (11): list_users, get_user, list_custom_fields, get_custom_field, create_custom_field, list_channels, list_closing_notes, list_templates, create_tag, update_tag, delete_tag

Tool parameters are defined in the server’s tool schemas (see src/tools/). Response shapes, rate limits, and API behavior come from the Respond.io Developer API and the @respond-io/typescript-sdk used under the hood.

Development

Testing

The project uses Jest for tests. Tests run against an in-memory MCP transport and mock the Respond.io API so no real API key is needed for unit tests.

# Run tests once
npm run test

# Run tests in watch mode
npm run test:watch

# Run tests with coverage
npm run test:coverage

Tests cover:

Server & list_tools: All 28 tools are exposed; each has name, description, and inputSchema; server name/version and capabilities are reported.
All 28 tools (with mocked API): contact, messaging, conversation, comment, and workspace tools.
Validation & error scenarios: Unknown tool name, missing required args, invalid enums, empty arrays where non-empty is required.

Project Structure

mcp-server/
├── src/
│   ├── index.ts          # Main server implementation
│   ├── server.ts         # MCP server factory
│   ├── middlewares/      # Express middlewares
│   ├── protocol/         # STDIO / HTTP protocol handlers
│   ├── utils/            # Utility functions (API client)
│   └── tools/            # Tool definitions
├── dist/                 # Compiled JavaScript output
├── tests/                # Jest tests
├── .env.example          # Environment variable template
├── README.md             # Documentation
└── SETUP_GUIDE.md        # Setup instructions

Development Commands

# Run in development mode with auto-reload
npm run dev

# Build the project
npm run build

# Run linter
npm run lint

# Fix linting issues
npm run lint:fix

# Format code
npm run format

# Type check
npm run type-check

Code Quality

✅ TypeScript - Full type safety
✅ ESLint - Code quality and consistency
✅ Prettier - Code formatting
✅ Strict Mode - TypeScript strict mode enabled
✅ Error Handling - Comprehensive error handling
✅ Modular Design - Clean separation of concerns

API Rate Limits

The Respond.io API has rate limits. The server handles rate limit errors and includes rate limit information in error responses:

Retry-After - Seconds until retry is allowed
X-RateLimit-Limit - Request limit for the endpoint
X-RateLimit-Remaining - Remaining requests

Error Handling

The server provides detailed error messages:

// API errors include status codes and messages
{
  "error": "API Error 404: Contact not found"
}

// Network errors
{
  "error": "Network Error: timeout of 30000ms exceeded"
}

// Validation errors
{
  "error": "API Error 400: Validation error."
}

Security Best Practices

Never commit API keys - Use environment variables
Use HTTPS - All API calls use secure connections
Validate input - All inputs are validated before API calls
Error sanitization - Sensitive information is not exposed in errors

Contributing

Contributions are welcome! Please follow these guidelines:

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

Code Style

Follow TypeScript best practices
Use meaningful variable and function names
Add comments for complex logic
Ensure all tests pass
Run linter before committing

Troubleshooting

"UN_AUTHORIZED" Error

Check that your API key is correct in .env
Ensure the API key has the necessary permissions

"Contact not found" Error

Verify the contact identifier format (id:123, email:user@example.com, phone:+60123456789)
Check that the contact exists in your workspace

Rate Limit Errors

Wait for the time specified in the Retry-After header
Consider implementing exponential backoff for retries

Build Errors

Run npm install to ensure all dependencies are installed
Delete node_modules and dist folders, then reinstall

TypeScript/ESLint Warnings

Ensure you are using a supported TypeScript version (recommended: 5.3.x)
If you see warnings about any, use Record<string, unknown> or define explicit interfaces

Health Check Fails

Ensure the MCP server is running in HTTP mode (MCP_SERVER_MODE=http)
Check the correct port (PORT) is open and matches your configuration
Use curl http://localhost:3000/health to test

License

MIT License - see LICENSE file for details

Support

For issues and questions:

GitHub Issues: [Create an issue]
Respond.io API Documentation: https://docs.respond.io
Respond.io Support: https://support.respond.io

Changelog

Version 1.0.0

Initial release
Full support for Contact, Messaging, Conversation, Comment, and Space APIs
Comprehensive error handling
TypeScript with strict mode
MCP SDK integration
HTTP and STDIO dual-mode support
Health endpoint for monitoring

Acknowledgments

Built with Model Context Protocol SDK
Powered by Respond.io API

Made with ❤️ for seamless customer engagement automation

Name		Name	Last commit message	Last commit date
Latest commit History 40 Commits
.github		.github
public		public
src		src
tests		tests
.eslintrc.json		.eslintrc.json
.gitignore		.gitignore
.npmrc		.npmrc
.prettierrc.json		.prettierrc.json
CHANGELOG.md		CHANGELOG.md
CONTRIBUTING.md		CONTRIBUTING.md
Dockerfile		Dockerfile
LICENSE		LICENSE
PROJECT_SUMMARY.md		PROJECT_SUMMARY.md
README.md		README.md
SETUP_GUIDE.md		SETUP_GUIDE.md
docker-compose.yml		docker-compose.yml
eslint.config.mjs		eslint.config.mjs
jest.config.ts		jest.config.ts
package-lock.json		package-lock.json
package.json		package.json
tsconfig.json		tsconfig.json
tsconfig.test.json		tsconfig.test.json

Folders and files

Latest commit

History

Repository files navigation

Respond.io MCP Server

Features

Contact Management

Messaging

Conversations

Workspace Management

Comments

HTTP/STDIO Dual Mode

Prerequisites

Installation

Configuration

Environment Variables

Usage with Claude Desktop

1️⃣ STDIO Mode (Recommended for local Claude Desktop)

2️⃣ HTTP Mode (For remote/hosted or local HTTP integration)

Usage Examples

Contact Management

Get a Contact

Create a Contact

List Contacts with Filters

Add Tags

Create or Update Contact (upsert)

Merge Contacts

List Contact Channels

Update Contact Lifecycle

Messaging

Send Text Message

Send WhatsApp Template

Send Email

Send Attachment

Get Message

List Messages

Conversations

Assign Conversation

Close Conversation

Comments

Add Comment

Workspace Management

List Users

Get User

List Custom Fields

Get Custom Field

Create Custom Field

List Channels

List Closing Notes

List Message Templates (e.g. WhatsApp)

Create Tag

Update Tag

Delete Tag

Available Tools

Development

Testing

Project Structure

Development Commands

Code Quality

API Rate Limits

Error Handling

Security Best Practices

Contributing

Code Style

Troubleshooting

"UN_AUTHORIZED" Error

"Contact not found" Error

Rate Limit Errors

Build Errors

TypeScript/ESLint Warnings

Health Check Fails

License

Support

Changelog

Version 1.0.0

Acknowledgments

About

Topics

Resources

License

Packages