Repository navigation
Releases
v2.1.0: opt-in write surface
Help Scout MCP Server v2.1.0
Release Positioning
v2.1.0 adds the first write surface. It is minor, not major, because nothing
about a default install changes: with both write flags unset the server
advertises the same three tools as 2.0, over the same 55 read operations, and
every write path is absent from discovery, schema loading, and dispatch.
Turning writes on adds a fourth advertised tool, write_help_scout, and 13
conversation write operations behind it. The Mailbox API has no granular OAuth
scopes, so a token that can read a conversation can also reply to it. That makes
the server the permission boundary, and the gates are configuration an operator
sets deliberately rather than a claim about what the credential restricts.
Highlights
A Fourth Advertised Tool
write_help_scout executes one write operation using arguments that match the
schema loaded through describe_help_scout. It carries readOnlyHint: false and
destructiveHint: true, which is the worst case for the tool a host is about to
approve, not the best case for a particular call.
Discovery is unchanged: search_help_scout labels write results with their
mutation class, describe_help_scout reports mutationClass and tier, and
read_help_scout refuses anything that mutates and names the tool that does not.
Write operation names never dispatch directly. No pre-2.0 client ever learned
one, so there is no compatibility debt to honor, and a bare createNote call
would slip past the gating, annotations, and confirmation that the write gateway
exists to enforce.
Two Tiers, Both Off By Default
| Flag | Enables |
|---|---|
HELPSCOUT_ENABLE_WRITES=true |
Tier 1: the 11 nonDestructive and reversible operations |
HELPSCOUT_ENABLE_CUSTOMER_VISIBLE_WRITES=true |
Tier 2: adds the 2 externallyVisible operations |
Tier 2 is additive and inert alone. With both unset, write_help_scout is not
returned by tools/list, write operations do not appear in search results, and
describe_help_scout reports a write operation name as unknown rather than as
gated, so the disabled surface is not a discoverable inventory of what an
operator could turn on.
Advertisement is built once per process, but execution gating is live: every
externallyVisible operation rechecks the flags at dispatch, so revoking the
customer-visible gate refuses the next customer-visible write immediately.
The 13 Operations
Tier 1, HELPSCOUT_ENABLE_WRITES:
| Operation | Mutation class | What it does |
|---|---|---|
createNote |
nonDestructive |
Adds an internal note, visible to teammates only |
createDraftReply |
nonDestructive |
Composes a customer reply and saves it unsent |
updateConversationStatus |
reversible |
Sets active, closed, or pending |
assignConversation |
reversible |
Assigns the conversation to a user |
unassignConversation |
reversible |
Returns it to the unassigned queue |
addConversationTags |
reversible |
Adds tags, keeping the existing ones |
removeConversationTags |
reversible |
Removes tags, keeping the rest |
updateConversationFields |
reversible |
Sets custom field values, preserving unlisted fields |
snoozeConversation |
reversible |
Snoozes until a future time |
unsnoozeConversation |
reversible |
Wakes a snoozed conversation |
moveConversation |
reversible |
Moves it to another inbox |
Tier 2, additionally HELPSCOUT_ENABLE_CUSTOMER_VISIBLE_WRITES:
| Operation | Mutation class | What it does |
|---|---|---|
sendReply |
externallyVisible |
Emails the customer immediately |
publishDraft |
externallyVisible |
Clears the draft flag, sending the pending reply |
Help Scout replaces the whole list on tag and custom field updates, so those
three operations read the record first and send the merged result. Each write
result carries operation, mutationClass, target, status, result, and a
cleanup block naming how to undo the change. Most of these endpoints answer
with no body, so the result names the read that confirms the new state instead of
claiming confirmation it does not have.
Draft First
Where an externally visible action has a non-visible variant, the non-visible
variant is the default and the visible one is a separate tier-2 operation.
createDraftReply pins draft: true and exposes no parameter that flips it into
a send. Composing reply text stays in tier 1 and never notifies anyone. Making a
customer see something takes a deliberate second step under a second flag.
The rule generalizes: no tier-1 operation may accept a parameter that makes it
externally visible.
Per-Call Confirmation
Enabling tier 2 is a gate, not a bypass. Every externallyVisible call must
carry three fields as siblings of arguments:
{
"name": "sendReply",
"arguments": { "conversationId": "12345", "text": "..." },
"confirm": true,
"confirmOperation": "sendReply",
"targetId": "12345"
}Missing, false, or mismatched values are rejected before any Help Scout request.
The requirement is stated in the write_help_scout tool description itself, so a
client reading tools/list learns it without a describe call.
These fields never appear in a per-operation schema: the schema describes the
Help Scout request, and confirmation authorizes the call that carries it. A
confirmation or dryRun field sent inside arguments is refused rather than
ignored, because a caller who misplaces one believes it took effect, and a
misplaced dryRun would otherwise perform the live mutation.
Dry Run
"dryRun": true beside arguments validates the input and reports the exact
request that would be sent, including the read a read-modify-write operation
performs first. It never contacts Help Scout and never simulates a result, and it
says plainly that Help Scout state was not checked. Help Scout offers no preview
or validate endpoint for these mutations, so that is the honest limit of what a
dry run can claim.
Retries Exempted For Writes
Reads keep retrying on 429 and 5xx. Every write surfaces the failure instead. A
retried reply is a second customer email and a retried note is a duplicate note,
and a 5xx does not prove the first request failed. Uncertain outcomes clear the
response cache and tell the caller to read the target back before retrying, so a
cached pre-write copy cannot be mistaken for confirmation that nothing landed.
What Is Deliberately Excluded
destructiveoperations are not exposed under any flag. No environment
variable turns them on. Exposing them needs its own contract work, not a third
flag added by analogy.- No delete operations of any kind.
- No admin configuration writes: workflows, webhooks, inbox settings, users,
teams, and tags are read-only. - No Docs write surface. Docs publishing is externally visible and unscoped.
- No conversation creation. The write dogfood harness seeds its own fixture
through the raw API rather than adding an operation for a test.
Verification
- 516 unit and integration tests pass.
- Live dogfood: 185 passed, 0 failed, against the real Help Scout account. Every
tier-1 operation mutated theMCP-TEST: write lifecycle fixtureconversation
over stdio and restored it, verified by reading the conversation or its threads
back. - Live stdio screen: 7/7 gateway cells, 9/9 read-only cells, 9/9 tier-1 cells,
9/9 tier-2 cells. - Gateway surface assertions confirm exactly four advertised tools when writes
are on, the write tool'sreadOnlyHint: falseanddestructiveHint: true,
mutation class and tier on every enabled operation, tier-2 operations reported
as unknown while their gate is off, andread_help_scoutrefusing a write
operation with a redirect. - Upstream denials that cannot be provoked on demand against a real account (401,
403, 412, 422, 423, 429, 5xx, and network failure) are covered by unit tests.
Breaking Changes
None. The default advertised surface is byte-identical to 2.0: three tools, 55
read operations, the same server instructions. Existing clients need no change,
and clients that parse content[].text keep working.
Enabling writes is opt-in and requires a server restart to change what is
advertised.
Compatibility
- OAuth2 credentials are unchanged:
HELPSCOUT_APP_IDand
HELPSCOUT_APP_SECRET. - Writes run with the private app's user permissions; a credential whose user
cannot write returns 403 as a structured tool error. HELPSCOUT_DOCS_API_KEYis still optional and Docs-only.- The navigator skill (2.0.0) is now standalone: it bundles no server and pins
no version. One repo URL distributes it everywhere:/plugin marketplace add
in Claude Code, Add marketplace from GitHub in claude.ai and Cowork, or a
folder copy in any other harness. The MCPB extension covers Claude Desktop
Chat and Cowork sessions. - Fixed: the packaged MCPB extension never started its server (the CLI's
direct-invocation guard did not recognize the extension layout), so installs
failed with "Unable to connect to extension server". The guard now resolves
symlinks and accepts thebuild/server/cli.jslayout.
Release Gate
Before tagging and publishing:
npm run type-checknpm run lintnpm run buildnpm test -- --runInBand --silentnpm run test:contractnpm pack --dry-run- package tarball install smoke
npm run mcpb:buildnpm run mcpb:smoke(the packed entry point must answer initialize; a build
once shipped that imported, did nothing, and exited 0)npm run mcpb:packnpm run test:docker:cinpm run test:docker- live dogfood seed with Docs credentials
npm run dogfood:full- write dogfood with
HELPSCOUT_ENABLE_WRITES=true, and the tier-2 pass with
HELPSCOUT_ENABLE_CUSTOMER_VISIBLE_WRITES=true MCP_DOGFOOD_ALLOW_CUSTOMER_VISIBLE=true npm run securitynpm run security:fullnpm auditbash scripts/version-audit.sh
Publi...
v2.0.0: Complete read parity behind a three-tool gateway
Help Scout MCP Server v2.0.0
Release Positioning
v2.0.0 replaces the wide tool surface with a three-tool gateway. The server now
advertises search_help_scout, describe_help_scout, and read_help_scout, and
routes every Help Scout read through them.
This is the read parity release. v1.9.0 was prepared but never published; its
scope ships here. No write tools are included.
The version is major because the advertised tool surface changed and because
names retired in the consolidation no longer resolve.
Highlights
Three Advertised Tools
search_help_scouttakes a plain-language intent and returns matching
operation names and descriptions. Query terms are expanded across support
synonyms, so "tickets" finds conversation operations.describe_help_scoutreturns full input schemas for up to ten named
operations.read_help_scoutexecutes one named operation. Unknown names come back with
suggestions rather than a bare failure.
The gateway lives in src/tools/gateway.ts. Operation definitions and handlers
stay in src/tools/index.ts.
55-Operation Read Parity
The registry behind the gateway covers the current Help Scout Mailbox and Docs
read surfaces: conversations and threads, original source, attachments, inboxes
and inbox metadata, saved replies, customers and contacts, organizations,
customer and organization properties, tags, users, teams, workflows, webhooks,
satisfaction ratings, the seven report categories, and the Docs API.
Every operation is read-only and annotated as such.
Page-Number Pagination
Collection operations use page-number pagination. Cursor parameters are gone from
the shared collection envelope. The one remaining cursor is the v3 Customers
path (listCustomers with useV3 or a cursor, and searchCustomersByEmail),
where cursor pagination is upstream Help Scout behavior rather than a server
choice.
Redaction Framing
REDACT_MESSAGE_CONTENT=true hides message bodies in responses. It is documented
as a context-saver: it keeps large message bodies out of the host's context
window. It is not a PII control and not a compliance boundary. Identifiers,
addresses, and metadata still flow through.
Dependencies
npm audit reports zero vulnerabilities at release.
Breaking Changes
Clients that call Help Scout tools by name are affected.
Names still in the registry continue to dispatch directly, so calls like
getConversation keep working as a compatibility path. Names retired in the
consolidation do not dispatch; they return a tool error pointing at
search_help_scout.
Migration
| Removed name | Replacement |
|---|---|
searchInboxes |
listAllInboxes with nameContains |
advancedConversationSearch, comprehensiveConversationSearch, structuredConversationFilter |
searchConversations convenience filters |
getConversationV3 |
getConversation with includeSystemActors: true |
getThreadsV3 |
getThreads with includeSystemActors: true |
getOriginalSourceRfc822 |
getOriginalSource with format: "rfc822" |
listCustomersV3 |
listCustomers with useV3: true or a cursor |
getCustomerAddress, listCustomerEmails, listCustomerPhones, listCustomerChats, listCustomerSocialProfiles, listCustomerWebsites |
getCustomerContacts |
listSystemUsers |
listUsers with includeSystemActors: true |
getSystemUser |
getUser with includeSystemActors: true |
listUserStatuses |
listUsers with includeStatuses: true |
getUserStatus |
getUser with includeStatus: true |
listInboxCustomFields, listInboxFolders, getInboxRouting |
getInbox with include: ["fields", "folders", "routing"] |
getDocsSiteRestrictions |
getDocsSite with includeRestrictions: true |
| 32 individual report tools | getCompanyReport, getConversationsReport, getProductivityReport, getUserReport, getHappinessReport, getChannelReport, getDocsReport, selecting a sub-report through report or channel |
No capability was dropped. Each retired name is reachable through a parameter on
its parent operation.
The simplest migration is to stop naming operations at all: call
search_help_scout, then describe_help_scout, then read_help_scout.
Compatibility
- OAuth2 credentials are unchanged:
HELPSCOUT_APP_IDand
HELPSCOUT_APP_SECRET. HELPSCOUT_DOCS_API_KEYis optional and only required for Docs operations.- Full read coverage needs Read scopes beyond Mailboxes and Conversations.
Reports, users, and tags each need their own scope. - Results still return
structuredContentplus a serialized JSON text block, so
clients that parsecontent[].textkeep working. - The navigator plugin pins
help-scout-mcp-server@2.0.0.
Release Gate
Before tagging and publishing:
npm run type-checknpm run lintnpm run buildnpm test -- --runInBand --silentnpm run test:contractnpm pack --dry-run- package tarball install smoke
npm run mcpb:buildnpm run mcpb:packnpm run test:docker:cinpm run test:docker- live dogfood seed with Docs credentials
npm run dogfood:fullnpm run securitynpm run security:fullnpm auditbash scripts/version-audit.sh
Publish Sequence
Publishing is manual apart from the Docker build.
- Merge the
devrelease-prep PR intomain. - Tag
v2.0.0onmainfrom the merge commit and push the tag. The tag push
triggers the Docker build and push. - Publish to npm by hand:
npm publish --otp=<2FA_CODE>. There is no CI publish
step. - Build the desktop bundle with
npm run mcpb:packand attach
help-scout-mcp-server-2.0.0.mcpbto the GitHub release. - Create the GitHub release from the
v2.0.0tag with these notes and the
.mcpbattached. - After npm publish succeeds, bump the navigator plugin pin to
help-scout-mcp-server@2.0.0and commit. Pinning before publish points users
at a version npm cannot serve. - Verify public install paths:
npx -y help-scout-mcp-server@2.0.0- navigator plugin install
.mcpbinstalldrewburchfield/help-scout-mcp-server:2.0.0
- Sync
mainback todev.
Verifying The Install
A connected client should list exactly three tools. If it lists more, or lists
none, the client is running a cached older build.
v1.7.0: Customer & Organization Intelligence
What's New
Customer Lookup
Look up any customer by name, email, or advanced query. Get their full profile with contact details, or search by exact email using the v3 API with cursor pagination.
listCustomers- Browse and search customerssearchCustomersByEmail- Find a customer by email addressgetCustomer- Full customer profile with embedded contacts and addressgetCustomerContacts- All contact channels (emails, phones, chats, social profiles, websites, address)
Organization Traversal
Explore organizations and traverse the full relationship graph: org to members to their conversations.
listOrganizations- Browse organizations sorted by activity, name, or sizegetOrganization- Organization profile with customer and conversation countsgetOrganizationMembers- Everyone in an organizationgetOrganizationConversations- Complete support history for an organization
Workflow Examples
Customer investigation: searchCustomersByEmail -> getCustomer -> getCustomerContacts -> structuredConversationFilter -> getThreads
Account review: listOrganizations -> getOrganization -> getOrganizationMembers -> getOrganizationConversations
Improvements
- Expanded PII redaction coverage across all customer and organization output paths
- Improved rate limit handling with proper retry behavior
- Better input validation with stricter schema checks
- Inbox cache now persists for 24 hours (previously refreshed too frequently)
- MCP SDK upgraded to 1.27.1
Install
npm install help-scout-mcp-server@1.7.0Or download the .mcpb file below for Claude Desktop one-click install.
Full Changelog: v1.6.2...v1.7.0
v1.6.2
What's Changed
Bug Fixes
- Fix date filtering: Replace
modifiedSinceAPI param withcreatedAtquery syntax across all search tools.createdAfternow correctly filters by creation date, not modification date. - Fix status defaults:
advancedConversationSearchandstructuredConversationFilternow default tostatus=allinstead of silently searching only active conversations. - Add date validation: ISO 8601 format validation on date inputs prevents query injection and strips milliseconds.
Tools Affected
searchConversationscomprehensiveConversationSearchadvancedConversationSearchstructuredConversationFilter
Install
npm install help-scout-mcp-server@1.6.2Or download the .mcpb file below for Claude Desktop one-click install.
Full Changelog: v1.6.1...v1.6.2
v1.6.1
What's New in v1.6.1
Bug Fixes
- Pagination Bug Fix: Multi-status searches now report accurate total counts. Previously, searching without a status filter (active/pending/closed in parallel) reported
totalResultscapped at the page limit instead of the real total across all statuses. Now returnstotalAvailable(sum of API totals) andtotalByStatusbreakdown. (#10)
Improvements
- Client-Side Date Filtering: New
createdBeforeparameter for all search tools with clear metadata distinguishing filtered counts from API totals - Partial Failure Transparency: Multi-status searches now surface structured error info when individual status queries fail, instead of silently returning incomplete results
- Stronger Error Type Guard:
isApiErrornow validates against the schema enum, preventing false matches on Node.js system errors
Security
- Upgraded
@modelcontextprotocol/sdkto 1.26.0 - Fixed vulnerabilities in axios, hono, and qs transitive dependencies
Installation
- Claude Desktop: Download
help-scout-mcp-server-1.6.1.mcpbbelow and double-click to install - npm:
npm install help-scout-mcp-server@1.6.1 - Docker:
docker pull drewburchfield/help-scout-mcp-server:1.6.1
v1.6.0: Inbox Auto-Discovery & MCP Tool Search Optimization
What's New
🔍 Inbox Auto-Discovery
- Inboxes are now automatically discovered on server connect
- Inbox IDs included directly in server instructions
- No more manual inbox lookups needed
⚡ MCP Tool Search Optimization
- Shorter tool descriptions (~60% reduction)
- Streamlined argument descriptions (~62% reduction)
- Workflow table in server instructions for better tool selection
- Added
structuredConversationFiltertool for ticket number lookups
🛠️ Improvements
- Async factory pattern:
HelpScoutMCPServer.create() - Multi-status search with
Promise.allSettled - Better error handling for inbox discovery failures
Installation
npm install help-scout-mcp-serverOr use the MCPB extension (attached) for one-click Claude Desktop installation.
v1.5.0 - MCP SDK Upgrade, Security Improvements & New Tools
What's New
🔧 Core Improvements
- MCP SDK v1.25.2: Latest Model Context Protocol SDK with enhanced compatibility
- Auth Alignment: Standardized environment variable naming (
HELPSCOUT_APP_ID/HELPSCOUT_APP_SECRET) to match Help Scout UI - Content Redaction: Renamed to
REDACT_MESSAGE_CONTENTfor clarity
🆕 New Tool
structuredConversationFilter: ID-based refinement and direct ticket number lookup (e.g., "Show ticket #42839")
🛡️ Security & Stability
- CI Branch Guard: Docker builds now verify tag is on main branch before publishing
- Enhanced Input Validation: Improved error handling from comprehensive code review
- Tool Discovery: Clearer descriptions and decision tree for better LLM tool selection
📦 Installation
NPM (Claude Code, Cursor, etc.):
```bash
npx help-scout-mcp-server
```
Docker:
```bash
docker run -e HELPSCOUT_APP_ID="your-id" -e HELPSCOUT_APP_SECRET="your-secret" drewburchfield/help-scout-mcp-server
```
Claude Desktop: Download the .mcpb file below and double-click to install.
Configuration
```
HELPSCOUT_APP_ID=your-app-id
HELPSCOUT_APP_SECRET=your-app-secret
```
See README for full documentation.
v1.3.0 - MCP SDK Upgrade & Enhanced Tool Guidance
🎉 What's New in v1.3.0
- 🆙 MCP SDK v1.17.4: Latest Model Context Protocol SDK with enhanced compatibility
- 🎯 DXT Format Compliance: Fixed manifest format to follow official Anthropic specification
- 📝 Enhanced Tool Guidance: Clear distinction between listing (
searchConversations) vs content-based searches (comprehensiveConversationSearch) - 🔧 Improved Search UX: Better tool descriptions prevent empty search term confusion
- 🛠️ Enhanced Version Management: Automated version bump script for all 6 version-sensitive files
- ✅ Test Reliability: Fixed async test handling and improved timeout management
- 🔒 Production Ready: Complete release workflow with DXT building and GitHub releases
📦 Installation Options
🎯 Claude Desktop (One-Click DXT)
- Download
helpscout-mcp-extension.dxtbelow - Double-click to install in Claude Desktop
- Enter Help Scout OAuth2 credentials
- Start using immediately!
📋 Manual NPM Installation
npx help-scout-mcp-server@1.3.0🐳 Docker
docker pull drewburchfield/help-scout-mcp-server:1.3.0🔧 Key Improvements
This release specifically addresses tool selection confusion by making it crystal clear:
- Use
searchConversations(without query) for "show me recent tickets" - Use
comprehensiveConversationSearch(with search terms) for "find tickets about billing"
Assets
- NPM Package: help-scout-mcp-server@1.3.0
- Docker Image:
drewburchfield/help-scout-mcp-server:1.3.0 - DXT Extension:
helpscout-mcp-extension.dxt(attached below)
v1.2.1 - DXT Documentation Update
🔗 DXT Enhancement Release
Minor update to improve the DXT extension experience:
✨ What's New
- 📚 Documentation Link: DXT now includes direct link to README documentation
- 🎨 Icon Fix: Corrected icon reference in DXT manifest
🎯 DXT Installation
Download the .dxt file below and double-click to install in Claude Desktop:
- One-click installation with OAuth2 credential setup
- Automatic updates when new versions are released
- No Node.js installation required
📦 Installation Options
- 🎯 DXT Extension: Download
.dxtfile for Claude Desktop - 💻 Command Line:
npx help-scout-mcp-server - 🐳 Docker:
docker run drewburchfield/help-scout-mcp-server
🔄 Auto-Update Test
This release tests the DXT auto-update mechanism in Claude Desktop. Existing DXT users should receive an automatic update notification.
v1.2.0: DXT Extension for One-Click Claude Desktop Installation
🎯 Major Feature: DXT Extension
The biggest addition in v1.2.0 is the DXT (Desktop Extensions) package for one-click installation in Claude Desktop, eliminating the need for manual Node.js setup and configuration.
✅ DXT Benefits:
- One-click installation in Claude Desktop
- Bundled dependencies (no Node.js setup required)
- Secure credential storage in OS keychain/Credential Manager
- User-friendly configuration UI
- Cross-platform support (macOS, Windows, Linux)
🚀 Other New Features
- Dependency injection with ServiceContainer for better code organization
- HTTP connection pooling for improved performance
- Reverse logic validation system for Help Scout API constraints
- Enhanced conversation search with multi-status support
🔧 Technical Improvements
- Windows compatibility for DXT extension builds
- Comprehensive test coverage with integration tests
- Security fixes addressing Semgrep findings
- Improved error handling with MCP-compliant responses
- Connection reuse and performance optimizations
📦 Installation Options
🎉 Recommended: Claude Desktop (DXT Extension)
Download the .dxt file below and install in Claude Desktop for the easiest setup experience.
NPM Package
npm install -g help-scout-mcp-server@1.2.0Docker
docker pull help-scout-mcp-server:1.2.0