The Help Scout MCP Server is a specialized implementation of the Model Context Protocol (MCP) that acts as a secure, stateless bridge between AI assistants (like Claude Desktop, Cursor, or Claude Code) and the Help Scout API README.md5-7 It enables LLMs to perform complex searches across conversations, manage customer profiles, and retrieve historical thread data directly within a chat interface README.md9-17
The server addresses the challenge of providing LLMs with real-time, authenticated access to customer support data while maintaining security through OAuth2 and optional PII redaction README.md20-21 src/index.ts157-160
The project follows a three-tier communication model where the server translates standardized MCP requests into authenticated Help Scout API calls. Since version 2.0, the server uses a Gateway Architecture helpscout-mcp-extension/manifest.json7 Instead of exposing dozens of individual tools, it advertises a compact set of gateway tools that delegate to an internal registry of over 55 read operations and 13 write operations README.md103-111
This diagram illustrates the transition from a user's natural language request to the execution of specific code entities within the server.
Sources: src/index.ts51-76 src/index.ts14-17 src/tools/gateway.ts1-20 README.md92-97
The server is organized into several functional layers that handle protocol communication, business logic, and data persistence (caching).
The entry point of the application initializes the HelpScoutMCPServer class src/index.ts51-76 which manages the connection over StdioServerTransport src/index.ts2 During startup, the server performs auto-discovery of available inboxes via discoverAndBuildInstructions to provide immediate context to the LLM src/index.ts94-163
For details, see Project Purpose and Architecture and Server Entry Point and Lifecycle.
The server exposes a consolidated tool surface: search_help_scout, describe_help_scout, read_help_scout, and the opt-in write_help_scout README.md103-113 These tools interface with the gatewayHandler src/index.ts16 Write operations are protected by a two-tier permission model and a confirmation contract for customer-visible actions src/index.ts35-49
For details, see Tool System and Resources and Prompts.
The helpScoutClient handles the OAuth2 Client Credentials flow, managing token acquisition and automatic refreshes README.md85-91 A separate HelpScoutDocsClient manages access to the Docs v1 API README.md99 The system includes an LRU-based caching layer and rate-limit handling helpscout-mcp-extension/manifest.json7
For details, see Data Layer and Security and Privacy.
The server is distributed via npm, Docker, and as a .mcpb bundle for installation in Claude Desktop README.md25-34 README.md76-83 It also supports the helpscout-navigator skill for enhanced operation selection README.md36-37
For details, see Getting Started and Deployment and Distribution.
The following table maps high-level system components to their primary implementation files.
| Component | Primary Code Entities | File Path |
|---|---|---|
| Server Entry | HelpScoutMCPServer | src/index.ts51 |
| Gateway Logic | gatewayHandler | src/tools/gateway.ts1-10 |
| Write Logic | WriteHandler | src/tools/writes.ts1-10 |
| Mailbox API Client | helpScoutClient | src/utils/helpscout-client.ts14 |
| Docs API Client | HelpScoutDocsClient | src/utils/helpscout-docs-client.ts10 |
| Schemas | ConversationSchema, CustomerSchema | src/schema/types.ts1-20 |
| Config/Security | validateConfig, config | src/utils/config.ts1-12 |
Sources: src/index.ts12-18 helpscout-mcp-extension/manifest.json27-41 README.md103-113
Refresh this wiki
This wiki was recently refreshed. Please wait 3 days to refresh again.