Skip to content

Releases

v2.1.0: opt-in write surface

Choose a tag to compare

@drewburchfield drewburchfield released this 30 Jul 19:47
56c3434

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

  • destructive operations 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 the MCP-TEST: write lifecycle fixture conversation
    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's readOnlyHint: false and destructiveHint: true,
    mutation class and tier on every enabled operation, tier-2 operations reported
    as unknown while their gate is off, and read_help_scout refusing 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_ID and
    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_KEY is 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 the build/server/cli.js layout.

Release Gate

Before tagging and publishing:

  • npm run type-check
  • npm run lint
  • npm run build
  • npm test -- --runInBand --silent
  • npm run test:contract
  • npm pack --dry-run
  • package tarball install smoke
  • npm run mcpb:build
  • npm run mcpb:smoke (the packed entry point must answer initialize; a build
    once shipped that imported, did nothing, and exited 0)
  • npm run mcpb:pack
  • npm run test:docker:ci
  • npm 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 security
  • npm run security:full
  • npm audit
  • bash scripts/version-audit.sh

Publi...

Read more

v2.0.0: Complete read parity behind a three-tool gateway

Choose a tag to compare

@drewburchfield drewburchfield released this 28 Jul 20:20
4635cb9

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_scout takes 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_scout returns full input schemas for up to ten named
    operations.
  • read_help_scout executes 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_ID and
    HELPSCOUT_APP_SECRET.
  • HELPSCOUT_DOCS_API_KEY is 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 structuredContent plus a serialized JSON text block, so
    clients that parse content[].text keep working.
  • The navigator plugin pins help-scout-mcp-server@2.0.0.

Release Gate

Before tagging and publishing:

  • npm run type-check
  • npm run lint
  • npm run build
  • npm test -- --runInBand --silent
  • npm run test:contract
  • npm pack --dry-run
  • package tarball install smoke
  • npm run mcpb:build
  • npm run mcpb:pack
  • npm run test:docker:ci
  • npm run test:docker
  • live dogfood seed with Docs credentials
  • npm run dogfood:full
  • npm run security
  • npm run security:full
  • npm audit
  • bash scripts/version-audit.sh

Publish Sequence

Publishing is manual apart from the Docker build.

  1. Merge the dev release-prep PR into main.
  2. Tag v2.0.0 on main from the merge commit and push the tag. The tag push
    triggers the Docker build and push.
  3. Publish to npm by hand: npm publish --otp=<2FA_CODE>. There is no CI publish
    step.
  4. Build the desktop bundle with npm run mcpb:pack and attach
    help-scout-mcp-server-2.0.0.mcpb to the GitHub release.
  5. Create the GitHub release from the v2.0.0 tag with these notes and the
    .mcpb attached.
  6. After npm publish succeeds, bump the navigator plugin pin to
    help-scout-mcp-server@2.0.0 and commit. Pinning before publish points users
    at a version npm cannot serve.
  7. Verify public install paths:
    • npx -y help-scout-mcp-server@2.0.0
    • navigator plugin install
    • .mcpb install
    • drewburchfield/help-scout-mcp-server:2.0.0
  8. Sync main back to dev.

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

Choose a tag to compare

@drewburchfield drewburchfield released this 25 Mar 16:59

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 customers
  • searchCustomersByEmail - Find a customer by email address
  • getCustomer - Full customer profile with embedded contacts and address
  • getCustomerContacts - 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 size
  • getOrganization - Organization profile with customer and conversation counts
  • getOrganizationMembers - Everyone in an organization
  • getOrganizationConversations - 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.0

Or download the .mcpb file below for Claude Desktop one-click install.

Full Changelog: v1.6.2...v1.7.0

v1.6.2

Choose a tag to compare

@drewburchfield drewburchfield released this 13 Feb 07:32
0e76bf2

What's Changed

Bug Fixes

  • Fix date filtering: Replace modifiedSince API param with createdAt query syntax across all search tools. createdAfter now correctly filters by creation date, not modification date.
  • Fix status defaults: advancedConversationSearch and structuredConversationFilter now default to status=all instead of silently searching only active conversations.
  • Add date validation: ISO 8601 format validation on date inputs prevents query injection and strips milliseconds.

Tools Affected

  • searchConversations
  • comprehensiveConversationSearch
  • advancedConversationSearch
  • structuredConversationFilter

Install

npm install help-scout-mcp-server@1.6.2

Or download the .mcpb file below for Claude Desktop one-click install.

Full Changelog: v1.6.1...v1.6.2

v1.6.1

Choose a tag to compare

@drewburchfield drewburchfield released this 13 Feb 06:30
ee89c87

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 totalResults capped at the page limit instead of the real total across all statuses. Now returns totalAvailable (sum of API totals) and totalByStatus breakdown. (#10)

Improvements

  • Client-Side Date Filtering: New createdBefore parameter 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: isApiError now validates against the schema enum, preventing false matches on Node.js system errors

Security

  • Upgraded @modelcontextprotocol/sdk to 1.26.0
  • Fixed vulnerabilities in axios, hono, and qs transitive dependencies

Installation

  • Claude Desktop: Download help-scout-mcp-server-1.6.1.mcpb below 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

Choose a tag to compare

@drewburchfield drewburchfield released this 21 Jan 18:18
ce1ede8

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 structuredConversationFilter tool 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-server

Or use the MCPB extension (attached) for one-click Claude Desktop installation.

v1.5.0 - MCP SDK Upgrade, Security Improvements & New Tools

Choose a tag to compare

@drewburchfield drewburchfield released this 08 Jan 21:12
ea5ee1b

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_CONTENT for 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

Choose a tag to compare

@drewburchfield drewburchfield released this 29 Aug 17:44

🎉 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)

  1. Download helpscout-mcp-extension.dxt below
  2. Double-click to install in Claude Desktop
  3. Enter Help Scout OAuth2 credentials
  4. 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

Choose a tag to compare

@drewburchfield drewburchfield released this 29 Jun 03:43

🔗 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 .dxt file 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

Choose a tag to compare

@drewburchfield drewburchfield released this 28 Jun 19:58

🎯 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.0

Docker

docker pull help-scout-mcp-server:1.2.0

🔗 Links