# Help Scout MCP

> Help Scout. Connect your help desk to any AI agent to manage customer support, tickets, and team notes. Use our tools to list active conversations, check customer history, add internal notes, and track satisfaction ratings directly from your workflow. It gives your agent the full context needed to act like a dedicated Support Coordinator.

## Overview
- **Category:** communication-messaging
- **Price:** Free
- **Tags:** shared-inbox, customer-experience, support-automation, live-chat, knowledge-base, conversation-tracking

## Description

You'll connect your Help Scout help desk to your AI agent, giving it the full context it needs to handle customer support and team operations. Your agent can list all active support threads and run advanced searches across your entire conversation history. It can pull up detailed profiles and history for any specific customer. You can also list every customer registered in your help desk, and even list all the support agents and users within the tenant. When you're working on a ticket, your agent can retrieve all details and transcripts for a single conversation. You can write private notes to a specific conversation for internal team reference, and you can change a conversation's status—like setting it to pending or closed.

To audit your setup, your agent can list all configured email inboxes used for support intake, list all available tags used to categorize conversations, and list all automated support workflows and rules. You can list all currently active support threads and run advanced searches across your entire history. You can retrieve customer satisfaction ratings to measure support performance. You'll also be able to list all available support workflows and rules. You'll use the tools to manage customer communication and support operations right from your chat window.

## Tools

### create_convo_note
Adds a private note to a specific conversation for internal team reference.

### get_conversation
Retrieves all details and transcripts for a single, specific support conversation.

### get_customer
Gets the detailed profile and history for a specific customer.

### list_conversations
Lists all currently active support threads and open tickets.

### list_customer_ratings
Retrieves a list of recent customer satisfaction scores.

### list_customers
Lists every customer registered in the help desk.

### list_mailboxes
Lists all configured email inboxes used for support intake.

### list_staff_users
Lists all support agents and users within the tenant.

### list_tags
Lists all available tags used to categorize conversations.

### list_workflows
Lists all automated support workflows and rules.

### search_conversations
Searches through the entire conversation history using keywords or criteria.

### update_convo_status
Changes the status of a conversation (e.g., active, pending, closed).

## Prompt Examples

**Prompt:** 
```
List all active conversations in the 'Main' mailbox.
```

**Response:** 
```
I've retrieved your active conversations. You have 5 threads requiring attention, including 'Refund request' from John, 'Feature question' from Maria, and 'API error' from David. Would you like to see the last message for any of these?
```

**Prompt:** 
```
Search for conversations from 'john.doe@example.com'.
```

**Response:** 
```
Searching Help Scout... I found 2 conversations for John Doe. One is 'Closed' regarding an old order, and the other is 'Active' regarding a new support query. Should I retrieve the full transcript for the active thread?
```

**Prompt:** 
```
Add an internal note to conversation ID 12345: 'Confirmed with engineering, fix arriving tomorrow'.
```

**Response:** 
```
Note added! I've successfully logged your update to conversation 12345. This note is internal-only and will not be seen by the customer. Would you like to set the status to 'Pending' while we wait for the fix?
```

## Capabilities

### View and Search Support Threads
List all support conversations or run advanced searches across your entire history.

### Manage Customer Profiles
Get detailed customer profiles and list all registered users in your help desk.

### Update and Collaborate on Tickets
Add private internal notes or change a conversation's status (e.g., pending, closed) directly through the chat.

### Audit Help Desk Setup
List configured mailboxes, available tags, and automated workflows to verify your operational setup.

### Measure Support Performance
Retrieve customer satisfaction ratings and list all available support workflows.

## Use Cases

### The Customer Needs a Refund (Support Manager)
A manager needs to know if John Doe has been contacting support about refunds before. They ask the agent to run `get_customer` for John Doe. The agent gets the profile, sees the history, and can confirm the last interaction was a billing query, allowing them to respond accurately.

### Client Follow-up Requires Internal Notes (Customer Success Manager)
A CSM is calling a client to follow up. They ask the agent to run `create_convo_note` on the client's active ticket. The note confirms an internal follow-up date, ensuring the client never sees the internal coordination details.

### Auditing a New Mailbox Setup (Operations Lead)
The ops lead needs to verify that the new 'Billing' mailbox is correctly configured. They ask the agent to run `list_mailboxes` and then `list_tags` to ensure all necessary categories and incoming channels are accounted for.

### Finding a Specific Error from 6 Months Ago (Support Agent)
A support agent needs to find an obscure API error mentioned in a conversation from half a year ago. They instruct the agent to use `search_conversations` with specific keywords and a date range, retrieving the exact thread ID for immediate follow-up.

## Benefits

- **Full Customer Context:** Stop jumping between tools. Use `get_customer` and `list_conversations` to instantly pull up a customer's full history and current active threads in one go.
- **Zero-Touch Collaboration:** Never lose an internal thought. Use `create_convo_note` to add private notes to a ticket. This keeps the customer out of the loop while giving your team the full context they need.
- **Operational Visibility:** Quickly audit your setup. Run `list_mailboxes` or `list_workflows` to see exactly which inboxes are receiving tickets and what automation rules are running.
- **Proactive Status Management:** When a fix is pending, use `update_convo_status` to change a ticket from 'Active' to 'Pending'. Your agent manages the lifecycle, not you.
- **Performance Measurement:** Track success metrics easily. Call `list_customer_ratings` to get the latest CSAT scores and measure the actual health of your support process.
- **Deep Search Capabilities:** Don't rely on keyword matching. Use `search_conversations` to dig through years of history and find the specific answer you need instantly.

## How It Works

The bottom line is that your AI client handles all the data calls; you just talk to it.

1. Subscribe to this server and provide your Help Scout OAuth Access Token.
2. Your AI client connects to the server and identifies the necessary action (e.g., 'I need to know the status of the billing issue').
3. The server executes the required tool (e.g., `get_conversation`) and returns the structured data to your AI client for a natural language summary.

## Frequently Asked Questions

**How do I use the `list_conversations` tool with Help Scout MCP Server?**
The agent runs `list_conversations` to pull a list of all active support threads. You can then follow up by asking the agent to get details for a specific conversation ID, like `get_conversation(ID)`.

**What is the difference between `list_conversations` and `search_conversations`?**
`list_conversations` gives you a count of currently open tickets. `search_conversations` lets you search through the entire history using keywords, like searching for 'billing error' across all past chats.

**Can I add internal notes using the `create_convo_note` tool?**
Yes. `create_convo_note` adds a private, internal note to a conversation ID. The customer will never see this note, keeping your team's communication separate from the customer view.

**Does the `get_customer` tool provide all historical data?**
The `get_customer` tool provides the customer's detailed profile and historical interactions. It's your starting point for any customer-facing query.

**How do I manage ticket statuses with `update_convo_status`?**
You tell the agent to update the status. You provide the conversation ID and the new status (e.g., 'Pending'). The agent runs `update_convo_status` and logs the change.

**How do I check all available tags using the `list_tags` tool?**
It lists every tag configured in your help desk. This helps you see what categories are available for classifying conversations, ensuring you don't miss a proper workflow tag.

**What is the difference between `list_mailboxes` and `list_staff_users`?**
The `list_mailboxes` tool shows all supported inboxes. The `list_staff_users` tool lists every agent account within your help desk, letting you know who can access and manage the support tickets.

**How do I find customer ratings using `list_customer_ratings`?**
It retrieves a list of recent customer satisfaction scores. You can monitor the overall health of your support operations and spot trends in customer happiness quickly.

**How do I get my Help Scout Access Token?**
You can generate an OAuth2 Access Token by creating an application in the **Help Scout Developer Portal** (developer.helpscout.com). Alternatively, if you are using a personal script, you can use the Client Credentials flow to obtain a token.

**Can I add internal notes to conversations?**
Yes! Use the `create_convo_note` tool. You must provide the `conversation_id` and the text of your note. This allows you to collaborate with your team without the customer seeing the message.

**How do I change the status of a support thread?**
Use the `update_convo_status` tool. Provide the conversation ID and the new status (active, pending, or closed). This helps you keep your mailbox organized.

**Is the integration secure for managing support data?**
Absolutely. The integration uses industry-standard OAuth 2.0 Bearer tokens over HTTPS. Your credentials are encrypted and stored securely within the Vinkius Cloud infrastructure.