What is MCP?

Model Context Protocol (MCP) is an open standard developed by Anthropic that creates a universal bridge between AI assistants and external tools. Instead of copy-pasting data between your inbox and an AI chat, MCP lets your AI assistant read, search, and act on your Helpmonks data directly — securely and in real time.

With the Helpmonks MCP server your AI assistant can:

• Search and browse conversations across all your mailboxes
• Read full email threads, notes, and attachments
• Reply to customers, add internal notes, and manage drafts
• Look up and manage contacts
• Organize work with labels, assignments, and status changes
• Query your knowledge base with AI-powered search
• List team members and mailbox configurations

How It Works

The MCP server acts as a secure bridge between your AI assistant and your Helpmonks account. Here's the flow:

1. Authentication — You provide an access token or API key so the AI acts as you, seeing only what you have permission to see.
2. Natural language — You describe what you need in plain English (e.g., "Find all unresolved conversations from Acme Corp").
3. AI processing — The assistant translates your request into the right MCP tool calls.
4. Secure execution — The MCP server calls the Helpmonks API on your behalf, enforcing your mailbox permissions and tenant isolation.
5. Results — Data flows back to the AI, which formats a helpful response for you.

Triage & Prioritize Your Inbox

Start your day by getting a quick snapshot of what needs attention — without opening Helpmonks at all.

Example prompts

• "Show me all unread inbox conversations across every mailbox"
• "List pending conversations assigned to me"
• "How many open conversations are in the Support mailbox right now?"
• "Show conversations labeled 'urgent' that are still in inbox status"

The AI uses list_conversations and list_mailboxes behind the scenes. Because the list endpoint returns pre-computed summaries (subject, excerpt, sender, dates), you get instant results without pulling full threads.

Draft & Send Replies with AI Assistance

Let your AI assistant read an entire conversation thread and craft a context-aware reply — then send it or save it as a draft for your review.

Example prompts

• "Read conversation [ID] and draft a polite reply explaining our refund policy"
• "Reply to the latest conversation from [email protected], thanking her for the feedback and letting her know we've escalated the issue"
• "Save a draft reply to conversation [ID] — I'll review it before sending"
• "Reply to conversation [ID] and then archive it"

The AI uses get_conversation to read the full thread context, then reply_to_conversation to send or save_draft to stage the message. You can even set the post-reply status (e.g., archived, closed) in a single step.

Search Conversations with Natural Language

Find any conversation instantly using everyday language — no more hunting through filters.

Example prompts

• "Search for conversations about 'invoice payment' in the Billing mailbox"
• "Find all closed conversations from last week mentioning a shipping delay"
• "Search for any conversation where a customer mentioned cancellation"

The AI uses search_conversations which performs full-text search across subjects and message bodies, with optional mailbox and status filters.

Manage Contacts & Customer Records

Look up customer information, create new contacts, or update existing records — all through conversation.

Example prompts

• "Look up the contact for [email protected]"
• "Create a new contact: Sarah Miller, [email protected], company: NewClient Inc"
• "Update the phone number for contact [ID] to +1-555-0123"
• "List all contacts from Acme Corp"

The AI uses list_contacts, get_contact, create_contact, and update_contact. Partial matching on email, name, and company makes finding contacts fast.

Organize with Labels & Assignments

Categorize, tag, and route conversations to the right team members without switching windows.

Example prompts

• "Assign conversation [ID] to team member Alex"
• "Add the 'billing-issue' label to conversation [ID]"
• "Create a new label called 'VIP' with a blue color for the Support mailbox"
• "Move conversation [ID] to 'pending' status"
• "Close all conversations currently in inbox that are labeled 'resolved'"

The AI combines update_conversation_assignee, update_conversation_labels, update_conversation_status, and the label management tools to keep your inbox organized.

Internal Notes & Team Collaboration

Add context for your team without the customer ever seeing it.

Example prompts

• "Add an internal note to conversation [ID]: 'Customer confirmed they want the annual plan'"
• "Read conversation [ID] and summarize the issue, then add the summary as an internal note"
• "Add a public note to conversation [ID] explaining the next steps"

The AI uses add_conversation_note with the is_public flag to control visibility. Internal notes keep your team aligned; public notes are visible to the customer.

Knowledge Base & Self-Service

Leverage AI-powered vector search across your published help articles and crawled website content to answer questions or draft replies grounded in your own documentation.

Example prompts

• "Search our knowledge base for articles about setting up email forwarding"
• "What does our documentation say about custom domains?"
• "Find a help article I can link to about resetting passwords"
• "Search our KB about billing and draft a reply to conversation [ID] using that info"

The AI uses knowledge_base_search with semantic vector search. It supports multi-turn conversations — follow-up questions refine the answer context. Use list_search_collections to discover what content is indexed.

Multi-Step Workflows

Chain multiple actions together in a single conversation to handle complex tasks.

Example prompts

• "Find all conversations from Acme Corp that are still open, summarize each one, and add a note to each with the summary"
• "Search for conversations about 'product demo request', assign them all to Maria, and label them 'demo'"
• "Read conversation [ID], draft a reply based on our KB article about refunds, save it as a draft, and assign the conversation to me"
• "List all mailboxes, then show me the 5 most recent conversations in each one"

The AI orchestrates multiple tool calls in sequence — searching, reading, replying, labeling, and assigning — to complete multi-step tasks that would normally require many clicks.

• Claude Desktop — Anthropic's desktop app (macOS, Windows, Linux)
• Claude.ai — Claude web app (Pro, Max, Team, Enterprise plans via custom connectors)
• ChatGPT — OpenAI's web interface (Pro/Plus with Developer Mode)
• Cursor — AI-powered code editor with built-in MCP support
• VS Code with Copilot — GitHub Copilot's MCP integration
• Raycast — Productivity launcher with MCP extensions
• Windsurf — AI IDE with native MCP support
• Claude Code — Anthropic's terminal-based coding agent
• Codex CLI — OpenAI's local coding agent

Step 1: Get Your Access Token

Your access token authenticates the AI as your user — it only sees mailboxes and conversations you have permission to access.

1. Log in to Helpmonks
2. Go to Profile → Access Tokens
3. Click Create New Token
4. Give it a name (e.g., "Claude Desktop") and copy the token

Important: Copy the token immediately — you won't be able to see it again after creation.

Step 2: Connect Your AI Client

Choose your AI client below and follow the instructions.

Claude Desktop

Edit your Claude Desktop configuration file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

Add the following configuration:

{
  "mcpServers": {
    "helpmonks": {
      "url": "https://mcp.helpmonks.com/sse",
      "headers": {
        "Authorization": "Bearer YOUR_ACCESS_TOKEN"
      }
    }
  }
}

Replace YOUR_ACCESS_TOKEN with the token you created in Step 1. Restart Claude Desktop completely (Cmd+Q / Alt+F4, then reopen).

Claude.ai (Web)

Custom connectors via remote MCP are available on Pro, Max, Team, and Enterprise plans:

1. Open Settings in the sidebar
2. Navigate to Connectors and select Add custom connector
3. Set Name to Helpmonks
4. Set URL to https://mcp.helpmonks.com
5. Authenticate with your access token when prompted

Cursor

Add to your project's .cursor/mcp.json file:

{
  "mcpServers": {
    "helpmonks": {
      "url": "https://mcp.helpmonks.com/sse",
      "headers": {
        "Authorization": "Bearer YOUR_ACCESS_TOKEN"
      }
    }
  }
}

Enable the Helpmonks MCP server in Cursor Settings. You should see a green dot when connected.

VS Code with GitHub Copilot

Add to your .vscode/mcp.json file:

{
  "servers": {
    "helpmonks": {
      "url": "https://mcp.helpmonks.com/sse",
      "headers": {
        "Authorization": "Bearer YOUR_ACCESS_TOKEN"
      }
    }
  }
}

Or use the Command Palette: MCP: Add Server → HTTP, enter the URL and name.

ChatGPT

1. Enable Developer Mode: Settings → Connectors → Advanced settings → Developer mode
2. In the Connectors tab, click Create
3. Set Name to Helpmonks and URL to https://mcp.helpmonks.com
4. Set Authentication to Custom Header, header name Authorization, value Bearer YOUR_ACCESS_TOKEN

Raycast

1. Run the Install Server command
2. Set Name to Helpmonks, Transport to HTTP
3. Set URL to https://mcp.helpmonks.com/sse
4. Add header Authorization: Bearer YOUR_ACCESS_TOKEN

Windsurf

Add to your mcp_config.json:

{
  "mcpServers": {
    "helpmonks": {
      "serverUrl": "https://mcp.helpmonks.com/sse",
      "headers": {
        "Authorization": "Bearer YOUR_ACCESS_TOKEN"
      }
    }
  }
}

Conversations (12 tools)

Full lifecycle management of email threads — list, read, reply, draft, label, assign, and close.

Tool	Description
list_conversations	List conversations with summary fields. Omit mailbox_id to query all mailboxes at once. Filter by status, assignee, or label.
get_conversation	Get the full thread — all emails, notes, labels, and assignee details.
create_conversation	Start a new email conversation in a mailbox.
reply_to_conversation	Send an outgoing reply email. Supports HTML, CC/BCC, and setting post-reply status.
save_draft	Save a reply, forward, or note as a draft without sending.
delete_draft	Permanently remove a saved draft.
update_conversation_status	Change status: inbox, assigned, archived, closed, pending, spam, trash.
update_conversation_assignee	Assign a conversation to a team member.
update_conversation_labels	Add or replace labels on a conversation.
add_conversation_note	Add internal or public notes to a conversation.
delete_conversation_note	Remove a note from a conversation.
delete_conversation	Permanently delete a conversation.

Contacts (5 tools)

Manage your customer and company contact database.

Tool	Description
list_contacts	List contacts with filtering by email, name, or company. Supports partial matching and pagination.
get_contact	Get full details of a specific contact.
create_contact	Create a new contact with email, name, company, and phone.
update_contact	Update any contact fields (partial updates supported).
delete_contact	Remove a contact from Helpmonks.

Labels (5 tools)

Create and manage labels for categorizing conversations.

Tool	Description
list_labels	List all labels configured in your account.
get_label	Get details of a specific label.
create_label	Create a label with name, color, parent, and mailbox scope.
update_label	Update label properties (name, color, nesting, mailbox scope).
delete_label	Delete a label (also removes it from all conversations and contacts).

Mailboxes (2 tools)

Browse and inspect your shared mailbox configuration.

Tool	Description
list_mailboxes	List all mailboxes accessible to you, including email address, name, and subscribers.
get_mailbox	Get full details of a specific mailbox.

Users (2 tools)

List and look up your team members.

Tool	Description
list_users	List all team members (active by default).
get_user	Get details of a specific team member.

Search (3 tools)

Powerful search across conversations and knowledge base content.

Tool	Description
search_conversations	Full-text search across all conversations. Filter by mailbox and status.
knowledge_base_search	AI-powered vector search across help articles and crawled website content. Supports multi-turn follow-up questions.
list_search_collections	Discover what knowledge base and website content is indexed and available for vector search.

Authentication Methods

The Helpmonks MCP server supports multiple authentication methods to work with any MCP client:

Access Token (Recommended)

Pass your access token in any of these ways:

• Authorization: Bearer YOUR_TOKEN header (standard, recommended)
• x-access-token: YOUR_TOKEN header
• ?access_token=YOUR_TOKEN query parameter
• HELPMONKS_ACCESS_TOKEN environment variable (for stdio/local mode)

API Key

Alternatively, authenticate with your API key:

• HTTP Basic Auth (API key as username)
• ?api_key=YOUR_KEY query parameter
• HELPMONKS_API_KEY environment variable

Security

All requests are scoped to your user account. You only see mailboxes and conversations you have permission to access. Tenant isolation is enforced server-side — there is no way to access another account's data. The MCP server is available exclusively to paid Helpmonks accounts.

Be specific

The more specific your prompt, the better the result. Instead of "show me conversations," try "show me open conversations in the Support mailbox assigned to me."

Use context chaining

Within a single AI conversation, the assistant remembers previous results. You can say "now assign that conversation to Alex" without repeating the conversation ID.

Leverage multi-step prompts

Don't be afraid to combine actions: "Search for conversations about shipping delays, label them all as 'logistics', and assign them to the operations team."

Draft before sending

For important replies, ask the AI to save a draft first. Review it in Helpmonks, then send when you're satisfied.

Knowledge base for replies

Ask the AI to search your knowledge base and use the results to draft an informed reply. This ensures consistency with your published help articles.

No tools appear / AI can't connect

• Verify your access token is correct and hasn't expired
• Ensure the MCP server URL is exactly https://mcp.helpmonks.com/sse
• Restart your AI client completely after configuration changes
• Check that your Helpmonks account is on a paid plan

"Access denied" on specific mailboxes

The MCP server enforces your user permissions. If you can't access a mailbox via MCP, verify that you're a subscriber of that mailbox in Helpmonks settings.

Slow responses

Large conversation threads may take a moment. Use list_conversations (which returns lightweight summaries) instead of get_conversation when you just need an overview. Only pull full threads when you need the complete email history.