> **Building with AI coding agents?** Install the authstack plugin with one command. This equips your agent with accurate Scalekit implementation patterns.
>
> **Recommended** (the `-y` flags skip prompts, so the command runs without an interactive terminal):
> ```bash
> npx -y @scalekit-inc/cli setup -y
> ```
>
> Global:
> ```bash
> npm install -g @scalekit-inc/cli
> scalekit setup -y
> ```
>
> Supports Claude Code, Cursor, GitHub Copilot, Codex + skills for other Agent Skills-compatible agents in `~/.agents/skills`.
> Skills: integrate-agentkit, implement-saaskit, add-mcp-oauth, implement-sso, implement-scim.
> [Full setup guide](https://docs.scalekit.com/dev-kit/build-with-ai/)

---

# Connect AI agents to the Help Scout MCP server

The Help Scout MCP connector routes your AI agent's tool calls to Help Scout's own MCP server through Scalekit. Each user signs in to Help Scout once, and Scalekit stores and refreshes their tokens, so your agent never handles credentials. It comes with 54 tools.

**Authentication:** OAuth 2.1/DCR
**Categories:** Customer Support, Communication
**Tools:** 54: 54 read, 0 write, 0 destructive
**Users sign in with:** OAuth
**OAuth app:** Your own Help Scout MCP server app
**Built by:** Vendor MCP
**Try it:** [Playground in the Scalekit dashboard](https://app.scalekit.com/ws/signup?sk_intent=playground&provider=HELPSCOUTMCP)

## Setup

1. ### Install the SDK

   **Node.js**

   ```bash
   npm install @scalekit-sdk/node dotenv
   ```

   **Python**

   ```bash
   pip install scalekit-sdk-python python-dotenv
   ```

2. ### Set your credentials

   Add your Scalekit credentials to your `.env` file. Find values in **[app.scalekit.com](https://app.scalekit.com)** > **Developers** > **API Credentials**.

   ```sh title=".env"
   SCALEKIT_ENVIRONMENT_URL=<your-environment-url>
   SCALEKIT_CLIENT_ID=<your-client-id>
   SCALEKIT_CLIENT_SECRET=<your-client-secret>
   ```

3. ### Create the Help Scout MCP connection

   In **AgentKit > Connections**, create a Help Scout MCP connection and copy its redirect URI. The name you give it is the `connection_name` your code passes. See [Configure connections](/agentkit/connections/).

4. ### Register an OAuth app

   Help Scout MCP server connections use your own OAuth app. Register one with Help Scout MCP server and add the redirect URI you copied.

   Then enter the app's Client ID and Client Secret on the Help Scout MCP connection.

5. ### Authorize a user and make your first call

   **Node.js** (`quickstart.mts`)

   ```typescript
   import { ScalekitClient } from '@scalekit-sdk/node'
   import 'dotenv/config'
   import { createInterface } from 'node:readline/promises'

   const scalekit = new ScalekitClient(
     process.env.SCALEKIT_ENVIRONMENT_URL,
     process.env.SCALEKIT_CLIENT_ID,
     process.env.SCALEKIT_CLIENT_SECRET,
   )
   const actions = scalekit.actions

   const connector = 'helpscoutmcp'
   const identifier = 'user_123'

   // Generate an authorization link for the user
   const { link } = await actions.getAuthorizationLink({ connectionName: connector, identifier })
   console.log('Authorize Help Scout MCP:', link)
   const rl = createInterface({ input: process.stdin, output: process.stdout })
   await rl.question('Press Enter after authorizing...')
   rl.close()

   // Make your first call
   const result = await actions.executeTool({
     connector,
     identifier,
     toolName: 'helpscoutmcp_get_me',
     toolInput: {},
   })
   console.log(result)
   ```

   ```bash
   npx tsx quickstart.mts
   ```

   **Python** (`quickstart.py`)

   ```python
   import os
   from scalekit import ScalekitClient
   from dotenv import load_dotenv
   load_dotenv()

   scalekit_client = ScalekitClient(
       env_url=os.getenv("SCALEKIT_ENVIRONMENT_URL"),
       client_id=os.getenv("SCALEKIT_CLIENT_ID"),
       client_secret=os.getenv("SCALEKIT_CLIENT_SECRET"),
   )
   actions = scalekit_client.actions

   connection_name = "helpscoutmcp"
   identifier = "user_123"

   # Generate an authorization link for the user
   link_response = actions.get_authorization_link(
       connection_name=connection_name,
       identifier=identifier,
   )
   print("Authorize Help Scout MCP:", link_response.link)
   input("Press Enter after authorizing...")

   # Make your first call
   result = actions.execute_tool(
       tool_input={},
       tool_name="helpscoutmcp_get_me",
       connection_name=connection_name,
       identifier=identifier,
   )
   print(result)
   ```

   ```bash
   python quickstart.py
   ```

   Each user signs in once. See [Authorize a user](/agentkit/tools/authorize/) for the full flow and statuses.

## Tools

Pass the exact name to `execute_tool`, with an input like each tool's example. To ask for a tool that's missing, use the [request form](https://scalekitsupport.portal.usepylon.com/forms/request-a-connector-tool).

**Node.js**

```typescript
const result = await actions.executeTool({
  toolName: 'helpscoutmcp_docs_get_article',
  toolInput: {
    articleId: '<articleId>',
  },
  connector: 'helpscoutmcp',
  identifier: 'user_123',
})
```

**Python**

```python
result = actions.execute_tool(
    tool_name="helpscoutmcp_docs_get_article",
    tool_input={
        "articleId": "<articleId>",
    },
    connection_name="helpscoutmcp",
    identifier="user_123",
)
```

`result.data` is the app's response as JSON, and `result.execution_id` (`executionId` in Node.js) is the ID of the call.

### `helpscoutmcp_docs_get_article`

Get Docs Article · Read-only

Get a single Docs article by ID (Requires linked Docs API key)

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `articleId` (`string`, required): Article ID
- `draft` (`boolean`, optional): Get draft version if true

Example input: `{"articleId":"<articleId>"}`

### `helpscoutmcp_docs_get_site`

Get Docs Site · Read-only

Get a Docs site by ID (Requires linked Docs API key)

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `siteId` (`string`, required): Site ID

Example input: `{"siteId":"<siteId>"}`

### `helpscoutmcp_docs_list_articles`

List Docs Articles · Read-only

List articles in a collection or in one category. Pass exactly one of collectionId or categoryId; use docs_list_categories to find a category ID. status: "notpublished" returns articles that aren't live, including ones that were published before. A live article with unpublished edits has status "published" and hasDraft: true. Results are paginated. Pass page=1 (default) to start; check the response for total pages and request subsequent pages as needed. (Requires linked Docs API key)

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `categoryId` (`string`, optional): Category ID
- `collectionId` (`string`, optional): Collection ID
- `order` (`string`, optional): No description. One of: `asc`, `desc`.
- `page` (`number`, optional): No description.
- `pageSize` (`integer`, optional): Articles per page, up to 100. Defaults to 50.
- `sort` (`string`, optional): No description. One of: `number`, `status`, `name`, `popularity`, `createdAt`, `updatedAt`.
- `status` (`string`, optional): No description. One of: `all`, `published`, `notpublished`.

Example input: `{}`

### `helpscoutmcp_docs_list_categories`

List Docs Categories · Read-only

List the categories in a Docs collection. Pass a category ID to docs_list_articles to list only that category's articles. Results are paginated. Pass page=1 (default) to start; check the response for total pages and request subsequent pages as needed. (Requires linked Docs API key)

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `collectionId` (`string`, required): Collection ID
- `order` (`string`, optional): No description. One of: `asc`, `desc`.
- `page` (`number`, optional): No description.
- `sort` (`string`, optional): No description. One of: `number`, `order`, `name`, `articleCount`, `createdAt`, `updatedAt`.

Example input: `{"collectionId":"<collectionId>"}`

### `helpscoutmcp_docs_list_collections`

List Docs Collections · Read-only

List collections in a Docs site. Results are paginated. Pass page=1 (default) to start; check the response for total pages and request subsequent pages as needed. (Requires linked Docs API key)

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `page` (`number`, optional): No description.
- `siteId` (`string`, optional): Filter by site ID
- `visibility` (`string`, optional): public (customers can see it) or private (admin only). Defaults to all. One of: `all`, `public`, `private`.

Example input: `{}`

### `helpscoutmcp_docs_list_sites`

List Docs Sites · Read-only

List Docs sites. Results are paginated. Pass page=1 (default) to start; check the response for total pages and request subsequent pages as needed. (Requires linked Docs API key)

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `page` (`number`, optional): Page number (default 1)

Example input: `{}`

### `helpscoutmcp_docs_search_articles`

Search Docs Articles · Read-only

Search Docs articles by query. Results are paginated. Pass page=1 (default) to start; check the response for total pages and request subsequent pages as needed. An article is visible to customers only if it is published AND its collection is public: status: "published" alone still returns articles in private (admin-only) collections. To find content you can send a customer, pass status: "published" and visibility: "public". (Requires linked Docs API key)

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `query` (`string`, required): Search query string. Sent to the Help Scout Docs API article search endpoint: https://developer.helpscout.com/docs-api/articles/search/
- `collectionId` (`string`, optional): Limit to a collection
- `page` (`number`, optional): No description.
- `siteId` (`string`, optional): Limit to a site
- `status` (`string`, optional): No description. One of: `all`, `published`, `notpublished`.
- `visibility` (`string`, optional): Visibility of the article's collection: public (customers can see it) or private (admin only). Defaults to all. One of: `all`, `public`, `private`.

Example input: `{"query":"<query>"}`

### `helpscoutmcp_get_chat_report`

Get Chat Report · Read-only

Get the Chat report for a date range: live chat volume, wait and response times, and chat length. In `current`: volume.chatConversations is every chat conversation created in the range, including third-party chat integrations. Every other metric covers Beacon chats only. completedChats and missedChats count Beacon chat sessions, and one conversation can hold more than one, so completedChats + missedChats can be higher or lower than chatConversations. completedChats were accepted and then ended by either side. missedChats were never connected to a user, usually because no one was available, so the question moved to email. chatsPerDay is chatConversations divided by the days in the range. All times are in seconds, and are 0 (not null) when there were no chats. responses.waitTime is the average wait from the visitor starting the chat (or entering their email, when Beacon requires one) to a user accepting or being assigned it. Missed chats are excluded. responses.responseTime is the average time a customer waited for a user reply. Only the first user reply after each customer message counts, and chats with no user reply are excluded. resolutions.duration is the average time from a chat being accepted to it ending. resolutions.messagesPerChat is the average number of messages per chat. The top-level waitTime, responseTime, messagesPerChat and duration objects bucket chats by that metric, as a count and percent per range id. waitTime: 1=under 1 min, 2=1–2 min, 3=2–10 min, 4=10–20 min, 5=20 min or more. responseTime: 1=under 1 min, 2=1–2 min, 3=2–5 min, 4=5–10 min, 5=10 min or more. messagesPerChat: 1=under 5, 2=5–10, 3=10–20, 4=20–30, 5=30 or more. duration: 1=under 5 min, 2=5–10 min, 3=10–20 min, 4=20–30 min, 5=30 min or more. Ranges may not be listed in id order. Pass previousStart and previousEnd to also get `previous` (the same metrics for that range), `deltas` (percentage change per metric), and previousCount and previousPercent on each range. previousPercent is rounded down to a whole number, unlike percent. Without a comparison range, each bucket object's previousCount is 0, not missing. For one user's or team's chat metrics use get_user_chat_report.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `end` (`string`, required): End date/time in ISO 8601 format
- `start` (`string`, required): Start date/time in ISO 8601 format
- `folders` (`string`, optional): Comma-separated folder IDs
- `mailboxes` (`string`, optional): Comma-separated mailbox IDs
- `officeHours` (`boolean`, optional): Restrict metrics to office hours only. Ignored unless office hours are set up. Default false.
- `previousEnd` (`string`, optional): End of the prior comparison period (ISO 8601)
- `previousStart` (`string`, optional): Start of the prior comparison period (ISO 8601)
- `tags` (`string`, optional): Comma-separated tag IDs

Example input: `{"end":"<end>","start":"<start>"}`

### `helpscoutmcp_get_company_drilldown`

Get Company Drilldown · Read-only

Get the individual conversations behind the Company report for a date range, filtered by one metric dimension. Returns a paginated conversation list. Results are paginated. Pass page=1 (default) to start; check the response for total pages and request subsequent pages as needed.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `end` (`string`, required): End date/time in ISO 8601 format, e.g. 2025-01-31T23:59:59Z
- `range` (`string`, required): Metric dimension to drill into. One of: `replies`, `firstReplyResolved`, `resolved`, `responseTime`, `firstResponseTime`, `handleTime`.
- `start` (`string`, required): Start date/time in ISO 8601 format, e.g. 2025-01-01T00:00:00Z
- `mailboxes` (`string`, optional): Comma-separated mailbox IDs to filter
- `page` (`number`, optional): Page number for pagination
- `rangeId` (`number`, optional): Bucket index within the chosen range. For handleTime: 1=under 1 min, 2=1–2 min, 3=2–5 min, 4=5–10 min, 5=10 min or more. firstReplyResolved and resolved take no rangeId.
- `rows` (`integer`, optional): Results per page (default 25, max 50).
- `tags` (`string`, optional): Comma-separated tag IDs to filter
- `types` (`string`, optional): Filter by conversation type: email, chat, or phone. One of: `email`, `chat`, `phone`.

Example input: `{"end":"<end>","range":"replies","start":"<start>"}`

### `helpscoutmcp_get_company_report`

Get Company Report · Read-only

Get the overall company report with conversation metrics for a date range. The response includes a `users` array with each user's replies and customers helped within the range — use it for "how much did this person do in this period" questions.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `end` (`string`, required): End date/time in ISO 8601 format, e.g. 2025-01-31T23:59:59Z
- `start` (`string`, required): Start date/time in ISO 8601 format, e.g. 2025-01-01T00:00:00Z
- `mailboxes` (`string`, optional): Comma-separated mailbox IDs to filter
- `tags` (`string`, optional): Comma-separated tag IDs to filter

Example input: `{"end":"<end>","start":"<start>"}`

### `helpscoutmcp_get_conversation`

Get Conversation · Read-only

Get a single conversation by ID with full details. With embed: 'threads', the response includes every thread in the conversation, unpaginated, in one call. That can be very large on long conversations; if it is too big, use list_threads to page through them instead. Here, createdBy, assignee and thread authors can have type system_user: an AI agent, not a person. Other tools still report AI agents as type user.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `conversation_id` (`number`, required): The conversation ID
- `embed` (`string`, optional): Set to 'threads' to include every thread, unpaginated. One of: `threads`.

Example input: `{"conversation_id":1}`

### `helpscoutmcp_get_conversation_summary`

Get Conversation Summary · Read-only

Get a conversation summary: the customer's first message and the latest reply they received. Either can be null. Notes, drafts and replies that were never sent are excluded. A logged phone call is an inbound call, not a reply. A Beacon chat is one transcript, so both fields are null. customerMessageIsFirst is false when the oldest threads hold no customer message or could not be read, and customerMessage fell back to the oldest one among the 25 most recent threads; list_threads exposes the rest, one page at a time.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `conversation_id` (`number`, required): The conversation ID

Example input: `{"conversation_id":1}`

### `helpscoutmcp_get_conversations_drilldown`

Get Conversations Drilldown · Read-only

Get the individual conversations behind the Conversations report for a date range. Returns a paginated conversation list. Results are paginated. Pass page=1 (default) to start; check the response for total pages and request subsequent pages as needed.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `end` (`string`, required): End date/time in ISO 8601 format
- `start` (`string`, required): Start date/time in ISO 8601 format
- `folders` (`string`, optional): Comma-separated folder IDs
- `mailboxes` (`string`, optional): Comma-separated mailbox IDs
- `page` (`number`, optional): Page number for pagination
- `rows` (`integer`, optional): Results per page (default 25, max 50).
- `tags` (`string`, optional): Comma-separated tag IDs
- `types` (`string`, optional): Filter by conversation type: email, chat, or phone. One of: `email`, `chat`, `phone`.

Example input: `{"end":"<end>","start":"<start>"}`

### `helpscoutmcp_get_conversations_fields_drilldown`

Get Conversations Fields Drilldown · Read-only

Get the individual conversations behind the Conversations report, drilled down by a single field (tag, saved reply, workflow, or customer). Returns a paginated conversation list. Results are paginated. Pass page=1 (default) to start; check the response for total pages and request subsequent pages as needed.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `end` (`string`, required): End date/time in ISO 8601 format
- `field` (`string`, required): Which field to drill down by. One of: `tagid`, `replyid`, `workflowid`, `customerid`.
- `fieldid` (`number`, required): The ID of the field value chosen in `field` (e.g. the tag ID when field=tagid).
- `start` (`string`, required): Start date/time in ISO 8601 format
- `folders` (`string`, optional): Comma-separated folder IDs
- `mailboxes` (`string`, optional): Comma-separated mailbox IDs
- `page` (`number`, optional): Page number for pagination
- `rows` (`integer`, optional): Results per page (default 25, max 50).
- `tags` (`string`, optional): Comma-separated tag IDs
- `types` (`string`, optional): Filter by conversation type: email, chat, or phone. One of: `email`, `chat`, `phone`.

Example input: `{"end":"<end>","field":"tagid","fieldid":1,"start":"<start>"}`

### `helpscoutmcp_get_conversations_new_drilldown`

Get Conversations New Drilldown · Read-only

Get the individual new conversations behind the New Conversations report for a date range. Returns a paginated conversation list. Results are paginated. Pass page=1 (default) to start; check the response for total pages and request subsequent pages as needed.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `end` (`string`, required): End date/time in ISO 8601 format
- `start` (`string`, required): Start date/time in ISO 8601 format
- `folders` (`string`, optional): Comma-separated folder IDs
- `mailboxes` (`string`, optional): Comma-separated mailbox IDs
- `page` (`number`, optional): Page number for pagination
- `rows` (`integer`, optional): Results per page (default 25, max 50).
- `tags` (`string`, optional): Comma-separated tag IDs
- `types` (`string`, optional): Filter by conversation type: email, chat, or phone. One of: `email`, `chat`, `phone`.

Example input: `{"end":"<end>","start":"<start>"}`

### `helpscoutmcp_get_conversations_report`

Get Conversations Report · Read-only

Get the conversations report with volume and trend data for a date range.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `end` (`string`, required): End date/time in ISO 8601 format
- `start` (`string`, required): Start date/time in ISO 8601 format
- `mailboxes` (`string`, optional): Comma-separated mailbox IDs
- `tags` (`string`, optional): Comma-separated tag IDs

Example input: `{"end":"<end>","start":"<start>"}`

### `helpscoutmcp_get_custom_fields`

Get Custom Fields · Read-only

Get the custom field values set on a specific conversation.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `conversation_id` (`number`, required): The conversation ID

Example input: `{"conversation_id":1}`

### `helpscoutmcp_get_customer`

Get Customer · Read-only

Get a single customer by ID with full details including emails, phones, social profiles, etc.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `customer_id` (`number`, required): The customer ID

Example input: `{"customer_id":1}`

### `helpscoutmcp_get_docs_report`

Get Docs Report · Read-only

Get the Docs (knowledge base) report for a date range: visit metrics, popular and failed searches, and top articles and categories. In `current`: visitors is the number of visits (sessions). foundAnAnswerResult is the percentage of visits that viewed at least one article and failedResult the percentage that viewed none. Neither tracks whether the visitor went on to contact support. searchAction and browseAction split sessions between searching and viewing an article, as percentages. docsViewedPerVisit is article views per session. answers counts "great" article ratings. conversationsCreated counts conversations created in the range, not contacts that came from Docs. sentAnEmailResult, resolutionRate and timeSaved are always 0 and answerRate is always 100 when there is data: they are no longer calculated, so ignore them. popularSearches and failedSearches are the raw terms visitors typed. They are not merged by case and can include spam. Pass previousStart and previousEnd to also get `previous` (the same metrics for that range), `deltas` (percentage change per metric), and previousCount and deltaPercent on each list item. Use docs_list_sites to find site IDs.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `end` (`string`, required): End date/time in ISO 8601 format
- `start` (`string`, required): Start date/time in ISO 8601 format
- `previousEnd` (`string`, optional): End of the prior comparison period (ISO 8601)
- `previousStart` (`string`, optional): Start of the prior comparison period (ISO 8601)
- `sites` (`string`, optional): Comma-separated Docs site IDs to filter. Defaults to all sites.

Example input: `{"end":"<end>","start":"<start>"}`

### `helpscoutmcp_get_happiness_ratings`

Get Happiness Ratings · Read-only

Get individual satisfaction ratings with customer details. Supports filtering by rating value (great/ok/not-good) and tag. Useful for drilling into specific segments — e.g. all 'not good' ratings from VIP accounts. Results are paginated. Pass page=1 (default) to start; check the response for total pages and request subsequent pages as needed.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `end` (`string`, required): End date/time in ISO 8601 format
- `start` (`string`, required): Start date/time in ISO 8601 format
- `mailboxes` (`string`, optional): Comma-separated mailbox IDs
- `page` (`number`, optional): Page number for pagination
- `rating` (`string`, optional): Filter by rating value. Defaults to all. One of: `great`, `ok`, `not-good`, `all`.
- `sortField` (`string`, optional): Field to sort by. One of: `number`, `rating`, `modifiedAt`.
- `sortOrder` (`string`, optional): Sort direction. One of: `ASC`, `DESC`.
- `tags` (`string`, optional): Comma-separated tag IDs

Example input: `{"end":"<end>","start":"<start>"}`

### `helpscoutmcp_get_happiness_report`

Get Happiness Report · Read-only

Get the happiness/satisfaction report with rating data.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `end` (`string`, required): End date/time in ISO 8601 format
- `start` (`string`, required): Start date/time in ISO 8601 format
- `mailboxes` (`string`, optional): Comma-separated mailbox IDs
- `tags` (`string`, optional): Comma-separated tag IDs

Example input: `{"end":"<end>","start":"<start>"}`

### `helpscoutmcp_get_inbox`

Get Inbox · Read-only

Get details of a specific inbox: ID, name, slug, email and timestamps. Folders and custom fields are referenced as links only, not returned as data — use list_inbox_folders and list_inbox_custom_fields for those.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `mailbox_id` (`number`, required): The mailbox/inbox ID

Example input: `{"mailbox_id":1}`

### `helpscoutmcp_get_me`

Get Current User · Read-only

Get the currently authenticated user (resource owner).

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs: none.

Example input: `{}`

### `helpscoutmcp_get_organization`

Get Organization · Read-only

Get details for a specific organization.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `organization_id` (`number`, required): The organization ID

Example input: `{"organization_id":1}`

### `helpscoutmcp_get_productivity_report`

Get Productivity Report · Read-only

Get the productivity report with response time, resolution time, and replies data. The top-level responseTime, firstResponseTime, resolutionTime, handleTime and repliesToResolve objects bucket by that metric, as a count and percent per range id. responseTime and firstResponseTime: 1=under 15 min, 2=15–30 min, 3=30–60 min, 4=1–2 hours, 5=2–3 hours, 6=3–6 hours, 7=6–12 hours, 8=12–24 hours, 9=1–2 days, 10=2 days or more. resolutionTime: 1=under 4 hours, 2=4 hours–1 day, 3=1–2 days, 4=2–4 days, 5=4 days or more. handleTime: 1=under 1 min, 2=1–2 min, 3=2–5 min, 4=5–10 min, 5=10 min or more. repliesToResolve: the id is the number of replies, and 5 means 5 or more. Ranges may not be listed in id order.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `end` (`string`, required): End date/time in ISO 8601 format
- `start` (`string`, required): Start date/time in ISO 8601 format
- `mailboxes` (`string`, optional): Comma-separated mailbox IDs
- `officeHours` (`boolean`, optional): Restrict metrics to office hours only. Ignored unless office hours are set up. Default false.
- `tags` (`string`, optional): Comma-separated tag IDs

Example input: `{"end":"<end>","start":"<start>"}`

### `helpscoutmcp_get_saved_reply`

Get Saved Reply · Read-only

Get a specific saved reply with its full text body.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `mailbox_id` (`number`, required): The mailbox/inbox ID
- `saved_reply_id` (`number`, required): The saved reply ID

Example input: `{"mailbox_id":1,"saved_reply_id":1}`

### `helpscoutmcp_get_server_context`

Get Server Context · Read-only

Get server configuration and available capabilities

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs: none.

Example input: `{}`

### `helpscoutmcp_get_tag`

Get Tag · Read-only

Get a specific tag by ID.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `tag_id` (`number`, required): The tag ID

Example input: `{"tag_id":1}`

### `helpscoutmcp_get_user`

Get User · Read-only

Get a specific user by ID.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `user_id` (`number`, required): The user ID

Example input: `{"user_id":1}`

### `helpscoutmcp_get_user_chat_report`

Get User Chat Report · Read-only

Get chat metrics for a single user, or for a whole team when given a team ID, over a date range. Counts only Beacon chats the user (or any team member) took part in. In `current`: newConversations is the number of those chats created in the range, and totalDays the days in the range. waitTime, responseTime and duration are average seconds, measured as in get_chat_report: wait to be accepted, wait for a user reply, and time from acceptance to the chat ending. They are null when there were no chats, unlike get_chat_report, which returns 0. messagesPerChat is the average number of messages per chat. There are no completed or missed chat counts per user: use get_chat_report for those, company-wide. To compare users, call this once per user (list_users gives the IDs). Pass previousStart and previousEnd to also get `previous` and `deltas` (percentage change per metric).

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `end` (`string`, required): End date/time in ISO 8601 format
- `start` (`string`, required): Start date/time in ISO 8601 format
- `user` (`number`, required): Help Scout user ID, or a team ID to get combined metrics for its members.
- `mailboxes` (`string`, optional): Comma-separated mailbox IDs
- `officeHours` (`boolean`, optional): Restrict metrics to office hours only. Ignored unless office hours are set up. Default false.
- `previousEnd` (`string`, optional): End of the prior comparison period (ISO 8601)
- `previousStart` (`string`, optional): Start of the prior comparison period (ISO 8601)
- `tags` (`string`, optional): Comma-separated tag IDs

Example input: `{"end":"<end>","start":"<start>","user":1}`

### `helpscoutmcp_get_user_conversation_history`

Get User Conversation History · Read-only

Get a single user's conversations over a date range with per-conversation metrics (response time, resolve time, replies sent). These metrics cover the whole conversation across its lifetime, including other users' replies, not just this user or this range. Matches conversations this user has touched at any time that were also touched within the date range, not necessarily by this user. A touch is any update: user or customer replies, notes, assignment, status changes, or workflows. This is the intended behaviour of the User report's Total Conversations / Conversation History. It does not show what the user did within the range, and no report lists only the conversations a user worked on in a range. For in-range counts use the `users` array in get_company_report. Returns a paginated list, one row per conversation. Results are paginated. Pass page=1 (default) to start; check the response for total pages and request subsequent pages as needed.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `end` (`string`, required): End date/time in ISO 8601 format
- `start` (`string`, required): Start date/time in ISO 8601 format
- `user` (`number`, required): Help Scout user ID.
- `folders` (`string`, optional): Comma-separated folder IDs
- `mailboxes` (`string`, optional): Comma-separated mailbox IDs
- `officeHours` (`boolean`, optional): Restrict metrics to office hours only. Default false.
- `page` (`number`, optional): Page number for pagination
- `previousEnd` (`string`, optional): End of the prior comparison period (ISO 8601)
- `previousStart` (`string`, optional): Start of the prior comparison period (ISO 8601)
- `sortField` (`string`, optional): Field to sort by. One of: `number`, `repliesSent`, `responseTime`, `resolveTime`.
- `sortOrder` (`string`, optional): Sort direction. One of: `ASC`, `DESC`.
- `status` (`string`, optional): Filter by conversation status. One of: `active`, `pending`, `closed`.
- `tags` (`string`, optional): Comma-separated tag IDs
- `types` (`string`, optional): Filter by conversation type: email, chat, or phone. One of: `email`, `chat`, `phone`.

Example input: `{"end":"<end>","start":"<start>","user":1}`

### `helpscoutmcp_get_user_drilldown`

Get User Drilldown · Read-only

Get the individual conversations for a single user over a date range. Matches conversations this user has touched at any time that were also touched within the date range, not necessarily by this user. A touch is any update: user or customer replies, notes, assignment, status changes, or workflows. This is the intended behaviour of the User report's Total Conversations / Conversation History. It does not show what the user did within the range, and no report lists only the conversations a user worked on in a range. For in-range counts use the `users` array in get_company_report. Returns a paginated conversation list. Results are paginated. Pass page=1 (default) to start; check the response for total pages and request subsequent pages as needed.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `end` (`string`, required): End date/time in ISO 8601 format
- `start` (`string`, required): Start date/time in ISO 8601 format
- `user` (`number`, required): Help Scout user ID to drill into.
- `folders` (`string`, optional): Comma-separated folder IDs
- `mailboxes` (`string`, optional): Comma-separated mailbox IDs
- `page` (`number`, optional): Page number for pagination
- `rows` (`integer`, optional): Results per page (default 25, max 50).
- `tags` (`string`, optional): Comma-separated tag IDs
- `types` (`string`, optional): Filter by conversation type: email, chat, or phone. One of: `email`, `chat`, `phone`.

Example input: `{"end":"<end>","start":"<start>","user":1}`

### `helpscoutmcp_get_user_ratings`

Get User Ratings · Read-only

Get the individual satisfaction ratings for a single user's conversations over a date range. Returns a paginated ratings list. Results are paginated. Pass page=1 (default) to start; check the response for total pages and request subsequent pages as needed.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `end` (`string`, required): End date/time in ISO 8601 format
- `start` (`string`, required): Start date/time in ISO 8601 format
- `user` (`number`, required): Help Scout user ID.
- `folders` (`string`, optional): Comma-separated folder IDs
- `mailboxes` (`string`, optional): Comma-separated mailbox IDs
- `page` (`number`, optional): Page number for pagination
- `previousEnd` (`string`, optional): End of the prior comparison period (ISO 8601)
- `previousStart` (`string`, optional): Start of the prior comparison period (ISO 8601)
- `rating` (`string`, optional): Filter by rating value. Defaults to all. One of: `great`, `ok`, `not-good`, `all`.
- `sortField` (`string`, optional): Field to sort by. One of: `number`, `modifiedAt`, `rating`.
- `sortOrder` (`string`, optional): Sort direction. One of: `ASC`, `DESC`.
- `tags` (`string`, optional): Comma-separated tag IDs
- `types` (`string`, optional): Filter by conversation type: email, chat, or phone. One of: `email`, `chat`, `phone`.

Example input: `{"end":"<end>","start":"<start>","user":1}`

### `helpscoutmcp_get_user_status`

Get User Status · Read-only

Get one user's current status: email status (active or away) with any custom status text and emoji, and chat status with availability per inbox ID. email.updatedAt, when present, is the last time the email status or custom status was set. Only the current status is returned, not past ones. Light users have no email status. If no user has this ID, the response contains only userId, with no email or chat status.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `user_id` (`integer`, required): The user ID

Example input: `{"user_id":1}`

### `helpscoutmcp_health`

Health Check · Read-only

Check server health and connectivity

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs: none.

Example input: `{}`

### `helpscoutmcp_list_attachments`

List Attachments · Read-only

List attachments across the threads of a conversation. Returns filename, size, MIME type, and which thread each attachment belongs to.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `conversation_id` (`number`, required): The conversation ID

Example input: `{"conversation_id":1}`

### `helpscoutmcp_list_conversations`

List Conversations · Read-only

List or search conversations in Help Scout. Use the `query` parameter for advanced search (e.g. query="subject:billing" or query="tag:urgent"). Omit query to list recent conversations. Supports filtering by status, mailbox, folder, tag, and more. Use `custom_fields` to filter by custom field values (requires mailbox_id; multiple entries combine with AND). Results are paginated, 25 per page, newest first by default. For the next page, send the same filters with `cursor` set to the response's `nextCursor`; if the response has a `page` object instead, request the next `page`. A response with neither is the last page.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `assigned_to` (`number`, optional): Filter by assigned user ID. To find unassigned conversations, use query='(assigned:"Unassigned")' instead — passing 0 here is ignored by the API.
- `cursor` (`string`, optional): `nextCursor` from the previous response, to fetch the next page. Send the other parameters unchanged.
- `custom_fields` (`array`, optional): Filter conversations by custom field values. Multiple entries combine with AND — every field must match. Requires mailbox_id. Use list_inbox_custom_fields to discover field IDs and (for dropdowns) option IDs. Multiline text fields are not supported.
- `embed` (`string`, optional): Set to 'threads' to include truncated thread data. One of: `threads`.
- `folder` (`number`, optional): Filter by folder ID
- `mailbox_id` (`number`, optional): Filter by mailbox ID
- `modifiedSince` (`string`, optional): Only return conversations modified since this date/time (ISO 8601, e.g. 2026-01-31T00:00:00Z)
- `page` (`number`, optional): Page number (1-based), only for responses that carry a `page` object. Omit it for the first page.
- `query` (`string`, optional): Help Scout Inbox API conversation search syntax. Examples: "subject:refund", "email:user@example.com", "body:billing AND tag:urgent", "(assigned:\"Unassigned\")". Full syntax reference: https://developer.helpscout.com/mailbox-api/endpoints/conversations/list/
- `sortField` (`string`, optional): Sort field. Omit it unless the order matters: without a sort, results come newest first by conversation ID, which is faster to serve. One of: `createdAt`, `customerEmail`, `modifiedAt`, `number`, `score`, `status`, `subject`, `waitingSince`.
- `sortOrder` (`string`, optional): Sort order. Default: desc. One of: `asc`, `desc`.
- `status` (`string`, optional): Filter by status. Default: active. One of: `active`, `open`, `closed`, `pending`, `spam`, `all`.
- `tag` (`string`, optional): Filter by tag name

Example input: `{}`

### `helpscoutmcp_list_customer_emails`

List Customer Emails · Read-only

List email addresses for a customer.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `customer_id` (`number`, required): The customer ID

Example input: `{"customer_id":1}`

### `helpscoutmcp_list_customer_phones`

List Customer Phones · Read-only

List phone numbers for a customer.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `customer_id` (`number`, required): The customer ID

Example input: `{"customer_id":1}`

### `helpscoutmcp_list_customers`

List Customers · Read-only

List or search customers. Supports filtering by email, first name, last name, mailbox, and more. Results are paginated. Pass page=1 (default) to start; check the response for total pages and request subsequent pages as needed.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `email` (`string`, optional): Filter by email address
- `firstName` (`string`, optional): Filter by first name
- `lastName` (`string`, optional): Filter by last name
- `mailbox_id` (`number`, optional): Filter by mailbox ID
- `page` (`number`, optional): Page number
- `query` (`string`, optional): Help Scout Inbox API customer search syntax. Examples: '(firstName:"John")', '(email:"john@example.com")', 'modifiedAt:[2025-01-01T00:00:00Z TO *]'. Full syntax reference: https://developer.helpscout.com/mailbox-api/endpoints/customers/list/
- `sortField` (`string`, optional): Sort field. Defaults to createdAt. Note: the sort key for last-modified is modifiedAt, even though records carry updatedAt. One of: `createdAt`, `modifiedAt`, `firstName`, `lastName`.
- `sortOrder` (`string`, optional): No description. One of: `asc`, `desc`.

Example input: `{}`

### `helpscoutmcp_list_inbox_custom_fields`

List Inbox Custom Fields · Read-only

List custom fields for a specific inbox. Results are paginated. Pass page=1 (default) to start; check the response for total pages and request subsequent pages as needed.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `mailbox_id` (`number`, required): The mailbox/inbox ID
- `page` (`integer`, optional): Page number

Example input: `{"mailbox_id":1}`

### `helpscoutmcp_list_inbox_folders`

List Inbox Folders · Read-only

List folders within a specific inbox. Results are paginated. Pass page=1 (default) to start; check the response for total pages and request subsequent pages as needed.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `mailbox_id` (`number`, required): The mailbox/inbox ID
- `page` (`integer`, optional): Page number

Example input: `{"mailbox_id":1}`

### `helpscoutmcp_list_inboxes`

List Inboxes · Read-only

List the inboxes (mailboxes) you have access to. Returns each inbox's ID, name, slug, email and timestamps. Results are paginated at 50 per page. Pass page=1 (default) to start; check the response for total pages and request subsequent pages as needed. Folders and custom fields are not included — use list_inbox_folders and list_inbox_custom_fields.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `page` (`integer`, optional): Page number

Example input: `{}`

### `helpscoutmcp_list_organizations`

List Organizations · Read-only

List organizations. Results are paginated. Pass page=1 (default) to start; check the response for total pages and request subsequent pages as needed.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `page` (`number`, optional): Page number

Example input: `{}`

### `helpscoutmcp_list_saved_replies`

List Saved Replies · Read-only

List the saved replies (canned responses) available in an inbox. Returns the ID and name of every reply in one response — there is no pagination. Previews and full text are not included; call get_saved_reply with an ID for the body of a specific reply.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `mailbox_id` (`number`, required): The mailbox/inbox ID
- `include_chat_replies` (`boolean`, optional): Also include chat-only saved replies, which are otherwise omitted. Defaults to false

Example input: `{"mailbox_id":1}`

### `helpscoutmcp_list_tags`

List Tags · Read-only

List tags available in Help Scout. Results are paginated. Pass page=1 (default) to start; check the response for total pages and request subsequent pages as needed.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `page` (`number`, optional): Page number

Example input: `{}`

### `helpscoutmcp_list_team_members`

List Team Members · Read-only

List members of a specific team. Results are paginated. Pass page=1 (default) to start; check the response for total pages and request subsequent pages as needed.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `team_id` (`number`, required): The team ID
- `page` (`integer`, optional): Page number

Example input: `{"team_id":1}`

### `helpscoutmcp_list_teams`

List Teams · Read-only

List teams. Results are paginated. Pass page=1 (default) to start; check the response for total pages and request subsequent pages as needed.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `page` (`integer`, optional): Page number

Example input: `{}`

### `helpscoutmcp_list_threads`

List Threads · Read-only

List threads (messages) for a conversation: customer messages, agent replies, notes, and system events. Results are paginated at 25 per page, sorted newest first — so page 1 holds the most recent messages, and the oldest are the last entries on the last page. On a conversation the customer started, that is where their original question is. Pass page=1 (default) to start; check the response for total pages and request subsequent pages as needed. Alternatively, get_conversation with embed: 'threads' returns the threads in one call, but the response can be very large on long conversations. If it's too big, page through this tool instead.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `conversation_id` (`number`, required): The conversation ID
- `page` (`integer`, optional): Page number

Example input: `{"conversation_id":1}`

### `helpscoutmcp_list_user_statuses`

List User Statuses · Read-only

List the current status of every user: email status (active or away) with any custom status text and emoji, and chat status (unavailable, available, assign, or custom) with chat.mailboxStatuses giving chat availability per inbox ID. email.updatedAt, when present, is the last time the email status or custom status was set, so it does not show how long someone has been active or away. Light users are not included. Only the current status is returned, not past ones. Results are paginated, 50 users per page.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `page` (`integer`, optional): Page number

Example input: `{}`

### `helpscoutmcp_list_users`

List Users · Read-only

List users (team members / agents) in Help Scout. Results are paginated. Pass page=1 (default) to start; check the response for total pages and request subsequent pages as needed.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `page` (`number`, optional): Page number

Example input: `{}`

### `helpscoutmcp_list_workflows`

List Workflows · Read-only

List workflows (automations) configured in the account. Results are paginated. Pass page=1 (default) to start; check the response for total pages and request subsequent pages as needed.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `mailbox_id` (`number`, optional): Filter by mailbox ID
- `page` (`number`, optional): Page number
- `type` (`string`, optional): Filter by workflow type. One of: `automatic`, `manual`.

Example input: `{}`

### `helpscoutmcp_metrics`

Server Metrics · Read-only

Get server metrics snapshot (per-instance — each server process tracks its own counters independently)

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs: none.

Example input: `{}`

### `helpscoutmcp_search_conversation_content`

Search Conversation Content · Read-only

Search for conversations by keywords in message bodies and/or subjects. Provide plain search terms and the tool builds the Help Scout query — no query syntax required. Results are paginated, 25 per page, newest first by default. For the next page, send the same filters with `cursor` set to the response's `nextCursor`; if the response has a `page` object instead, request the next `page`. A response with neither is the last page.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `terms` (`array`, required): Search terms to look for, e.g. ["billing", "refund"]. All terms must match (AND logic).
- `cursor` (`string`, optional): `nextCursor` from the previous response, to fetch the next page. Send the other parameters unchanged.
- `days` (`number`, optional): Only return conversations modified in the last N days
- `mailbox_id` (`number`, optional): Filter by mailbox/inbox ID.
- `page` (`number`, optional): Page number (1-based), only for responses that carry a `page` object. Omit it for the first page.
- `search_in` (`string`, optional): Where to search. "body" = message content, "subject" = subject line, "both" = either. Default: "both". One of: `body`, `subject`, `both`.
- `status` (`string`, optional): Filter by status. Default: all. One of: `active`, `open`, `closed`, `pending`, `spam`, `all`.
- `tag` (`string`, optional): Filter results to conversations with this tag

Example input: `{"terms":[]}`

## Related

Other Customer Support connectors ([all 38](/agentkit/connectors/?category=customer-support)):

- [ServiceNow](/agentkit/connectors/servicenow/): Scalekit connector, OAuth, 112 tools
- [Zendesk](/agentkit/connectors/zendeskoauth/): Scalekit connector, OAuth, 137 tools
- [Jira Service Management](/agentkit/connectors/jiraservicemanagement/): Scalekit connector, OAuth, 72 tools


---

## More Scalekit documentation

| Resource | What it contains | When to use it |
|----------|-----------------|----------------|
| [/llms.txt](/llms.txt) | Structured index with routing hints per product area | Start here — find which documentation set covers your topic before loading full content |
| [/llms-full.txt](/llms-full.txt) | Complete documentation for all Scalekit products in one file | Use when you need exhaustive context across multiple products or when the topic spans several areas |
| [sitemap-0.xml](https://docs.scalekit.com/sitemap-0.xml) | Full URL list of every documentation page | Use to discover specific page URLs you can fetch for targeted, page-level answers |
