Pylon MCP Server

An MCP (Model Context Protocol) server for integrating with the Pylon API.

Features

This MCP server provides 38 tools for comprehensive Pylon API integration:

• User Management: Get current user, list and search team members

• Contacts: List, search, and create contacts

• Issues: Full CRUD, search, filter, snooze, and delete issues

• Tags: Get, create, add, and remove tags on issues

• External Issue Linking: Link/unlink Linear, Jira, GitHub, Asana issues

• Issue Followers: Get, add, and remove followers on issues

• Similar Issues: Find similar issues by requestor, account, or globally

• Knowledge Base: List knowledge bases and create articles

• Teams: List, get details, and create teams

• Accounts: List and get account details

• Attachments: Get metadata and create from URL

• Ticket Forms: List available submission forms

• Smart Caching: Automatic caching of GET requests with configurable TTL

• Retry Logic: Exponential backoff for transient failures (429, 5xx, timeouts)

Related MCP server: MCP Help Scout

Setup

Environment Variables

Set the following environment variables:

• PYLON_API_TOKEN: Your Pylon API token (required)

• PYLON_CACHE_TTL: Cache time-to-live in milliseconds (optional, default: 30000)

  • Set to 0 to disable caching

  • Example: PYLON_CACHE_TTL=60000 for 60-second cache

• PYLON_RETRY_MAX: Maximum retry attempts for transient failures (optional, default: 3)

  • Set to 0 to disable retries

  • Retries on: 429 (rate limit), 5xx (server error), network timeouts

  • Only retries idempotent requests (GET, HEAD, OPTIONS, PUT, DELETE)

  • Uses exponential backoff with jitter

  • Respects Retry-After header (capped at 30 seconds)

• PYLON_DEBUG: Set to true to enable debug logging (optional)

  • Logs request/response details and retry attempts to stderr

HTTP Request Timeout

All Pylon API requests have a 30-second timeout to prevent indefinite hanging. If a request takes longer than 30 seconds, it will fail with a timeout error. This helps identify:

• Slow API responses

• Network connectivity issues

• API performance problems

If you encounter timeout errors, check:

1. Your network connection

2. Pylon API status

3. Whether the operation is legitimately slow (e.g., large data queries)

Retry Behavior

The client automatically retries transient API failures with exponential backoff:

• Retried errors: HTTP 429 (rate limit), 5xx (server errors), network timeouts

• Not retried: 4xx client errors (400, 401, 403, 404, 422), POST/PATCH requests

• Backoff: min(1000ms × 2^attempt + random jitter, 30s), respects Retry-After header

• Default: 3 retry attempts. Set PYLON_RETRY_MAX=0 to disable.

Caching Behavior

The server implements intelligent caching to reduce API calls:

• Cached Operations: All GET requests (users, contacts, issues, teams, etc.)

• Not Cached: POST, PATCH, DELETE operations (creates, updates, deletes)

• Default TTL: 30 seconds

• Cache Key: Based on endpoint URL and query parameters

• Benefits: Reduces API rate limit usage, improves response times for repeated queries

Installation

Option 1: Install from npm (public)

This package is published publicly to npm:

# Run with npx (no auth required)
npx @customer-support-success/pylon-mcp-server

# Or install globally
npm install -g @customer-support-success/pylon-mcp-server

Option 2: Local Development

npm install
npm run build

Publishing Updates (for maintainers)

Preferred: tag and let GitHub Actions publish via npm Trusted Publishing (OIDC)

# Update version in package.json, then tag
git tag vX.Y.Z && git push origin vX.Y.Z

CI (.github/workflows/release.yml) will build/test and publish to npmjs with --provenance via trusted publisher.

Manual (maintainers only, if ever needed):

npm run build
npm publish --access public

Development

npm run dev

Testing

This project includes comprehensive unit tests for all functionality:

# Run tests once
npm test

# Run tests in watch mode
npm run test:watch

# Run tests with UI
npm run test:ui

# Run tests with coverage report
npm run test:coverage

Test Coverage:

• ✅ Attachment API (create from URL, file upload)

• ✅ User Management (get user, search users)

• ✅ Issue Management (get, create, update, filter, delete)

• ✅ Contact Management (get, search, create)

• ✅ Message Management (get messages with attachments)

• ✅ External Issue Linking (link/unlink Linear, Jira, GitHub, Asana)

• ✅ Issue Followers (get, add, remove followers)

• ✅ Error Handling (404, network errors)

Available Tools

User Tools

• pylon_get_me: Get current user information

• pylon_get_users: Get all team members and support agents

• pylon_search_users: Search for team members by name, email, or department

Contact Tools

• pylon_get_contacts: List contacts with optional search and limit

• pylon_search_contacts: Search for contacts by name, email, or company

• pylon_create_contact: Create a new contact

Issue Tools

• pylon_get_issues: List issues within a time range (uses start_time/end_time parameters)

• pylon_search_issues: Search and filter issues by state, tags, assignee, account, and more

• pylon_search_issues_by_status: Search by status name (handles custom status mapping automatically)

• pylon_create_issue: Create a new issue

• pylon_get_issue: Get details of a specific issue

• pylon_get_issue_with_messages: Get a complete issue with all messages in one call

• pylon_get_issue_messages: Get conversation history for an issue

• pylon_update_issue: Update issue status, priority, assignee, or replace all tags

• pylon_add_tags: Incrementally add tags to an issue (preserves existing tags, deduplicates)

• pylon_remove_tags: Incrementally remove specific tags from an issue (leaves other tags intact)

• pylon_snooze_issue: Temporarily hide an issue until a future date

• pylon_delete_issue: Permanently delete an issue (⚠️ destructive operation)

External Issue Linking Tools

• pylon_link_external_issue: Link an external issue (Linear, Jira, GitHub, Asana) to a Pylon issue

• pylon_unlink_external_issue: Unlink an external issue from a Pylon issue

Issue Followers Tools

• pylon_get_issue_followers: Get the list of followers for an issue

• pylon_add_issue_followers: Add users and/or contacts as followers to an issue

• pylon_remove_issue_followers: Remove followers from an issue

Searching by Custom Status

Pylon represents custom statuses (like "Waiting on Eng Input") as a combination of state and tag. We provide two ways to search by status:

Option 1: Use pylon_search_issues_by_status (Recommended)

This tool automatically maps status names to the correct state + tag combination:

# Just use the status name directly:
pylon_search_issues_by_status with status: "Waiting on Eng Input"

# Built-in mappings include:
- "Waiting on Eng Input" → state: on_hold + tag: waiting on eng
- "Waiting on Product" → state: on_hold + tag: waiting on product
- "Escalated" → state: on_hold + tag: escalated
- "In Progress" → state: waiting_on_you + tag: in progress
- "Blocked" → state: on_hold + tag: blocked

Option 2: Use pylon_search_issues with explicit state + tag

# Manually specify the combination:
pylon_search_issues with:
  - state: "on_hold"
  - tag: "waiting on eng"

Available Built-in States:

• new - New/unread issues

• waiting_on_you - Waiting for your response

• waiting_on_customer - Waiting for customer response

• on_hold - On hold (often used with custom status tags)

• closed - Closed/resolved issues

Note: The Pylon API does not support creating messages programmatically. Messages can only be created through the Pylon web UI or original channels (Slack, email, etc.).

Similar Issues Tools

• pylon_find_similar_issues_for_requestor: Find similar issues from the same contact

• pylon_find_similar_issues_for_account: Find similar issues from the same account/company

• pylon_find_similar_issues_global: Find similar issues across all users and companies

Knowledge Base Tools

• pylon_get_knowledge_bases: List all knowledge bases

• pylon_create_knowledge_base_article: Create a new article in a knowledge base

Team Tools

• pylon_get_teams: List all support teams

• pylon_get_team: Get details of a specific team

• pylon_create_team: Create a new support team

Account Tools

• pylon_get_accounts: List all customer accounts

• pylon_get_account: Get details of a specific account

Tag Tools

• pylon_get_tags: Get all available tags

• pylon_create_tag: Create a new tag

Ticket Form Tools

• pylon_get_ticket_forms: Get all ticket submission forms

Attachment Tools

• pylon_get_attachment: Get attachment metadata (includes a downloadable URL)

• pylon_create_attachment_from_url: Create an attachment from a URL

Tip: You usually get attachment_id from a message’s attachments[] returned by pylon_get_issue_messages or pylon_get_issue_with_messages. To download the actual file, fetch the returned url (signed URLs may expire).

Usage Examples

Running with Augment Code

Augment Code supports MCP servers through its Easy MCP feature in VS Code and JetBrains IDEs.

Setup in Augment Code (VS Code or JetBrains)

1. Open Augment Settings:

   • In VS Code: Open the Augment Code extension settings

   • In JetBrains: Navigate to Augment settings

2. Navigate to Easy MCP:

   • Find the "Easy MCP" pane in the settings

   • Click the "+" button to add a new MCP server

3. Configure the Server:

   Using npx from npmjs (Recommended)

   Add this configuration:

   {
     "pylon": {
       "command": "npx",
       "args": ["@customer-support-success/pylon-mcp-server"],
       "env": {
         "PYLON_API_TOKEN": "your_pylon_api_token_here",
         "PYLON_CACHE_TTL": "30000",
         "PYLON_RETRY_MAX": "3"
       }
     }
   }

   Note: PYLON_RETRY_MAX is optional and defaults to 3. Set to 0 to disable retries. PYLON_CACHE_TTL is optional and defaults to 30000ms (30 seconds). Set to 0 to disable caching.

   Option B: Using local installation

   If you've cloned this repository locally:

   {
     "pylon": {
       "command": "node",
       "args": ["/absolute/path/to/pylon-mcp-server/dist/index.js"],
       "env": {
         "PYLON_API_TOKEN": "your_pylon_api_token_here",
         "PYLON_CACHE_TTL": "30000",
         "PYLON_RETRY_MAX": "3"
       }
     }
   }

4. Get Your Pylon API Token:

   • Log into your Pylon dashboard

   • Navigate to Settings → API

   • Generate or copy your API token

   • Replace your_pylon_api_token_here with your actual token

5. Test the Integration:

   Once configured, you can ask Augment to use Pylon tools:

   "Check my Pylon user info"
   "Show me recent support issues"
   "Search for a contact by email"
   "Create a new support ticket"

Running Locally with Claude Desktop

1. Setup Environment:

   # Clone and install
   git clone <your-repo-url>
   cd pylon-mcp-server
   npm install
   npm run build
   
   # Set up environment variables
   cp .env.example .env
   # Edit .env and add your PYLON_API_TOKEN

2. Configure Claude Desktop:

Add this to your Claude Desktop MCP settings (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

Using npx from npmjs (Recommended)

{
  "mcpServers": {
    "pylon": {
      "command": "npx",
      "args": ["@customer-support-success/pylon-mcp-server"],
      "env": {
        "PYLON_API_TOKEN": "your_pylon_api_token_here",
        "PYLON_CACHE_TTL": "30000",
        "PYLON_RETRY_MAX": "3"
      }
    }
  }
}

Option B: Using local installation

{
  "mcpServers": {
    "pylon": {
      "command": "node",
      "args": ["/path/to/pylon-mcp-server/dist/index.js"],
      "env": {
        "PYLON_API_TOKEN": "your_pylon_api_token_here",
        "PYLON_CACHE_TTL": "30000",
        "PYLON_RETRY_MAX": "3"
      }
    }
  }
}

3. Test the Connection:

Restart Claude Desktop and try these commands in a conversation:

Use the pylon_get_me tool to check my Pylon user info

Use pylon_get_issues to show recent support tickets

Search for contacts with pylon_search_contacts using "customer@example.com"

Example Tool Usage

Once connected, you can use the available tools:

# User Management
"Get my user info" → uses pylon_get_me
"Search for users named John" → uses pylon_search_users

# Issue Management
"Show all open issues" → uses pylon_get_issues
"Create a new bug report" → uses pylon_create_issue
"Get issue #123 with all messages" → uses pylon_get_issue_with_messages
"Update issue status to resolved" → uses pylon_update_issue

# Similar Issues
"Find similar issues from this customer" → uses pylon_find_similar_issues_for_requestor
"Check if this account has had similar problems" → uses pylon_find_similar_issues_for_account

# Tags
"Show all available tags" → uses pylon_get_tags
"Add a tag to this issue" → uses pylon_add_tags

# External Linking
"Link this Linear ticket to the Pylon issue" → uses pylon_link_external_issue

# Issue Followers
"Add me as a follower on this issue" → uses pylon_add_issue_followers

# Attachments
"Create attachment from URL" → uses pylon_create_attachment_from_url

# Knowledge Base
"List all knowledge bases" → uses pylon_get_knowledge_bases
"Create a new help article" → uses pylon_create_knowledge_base_article

# Ticket Forms
"Show available ticket forms" → uses pylon_get_ticket_forms

# Team & Account Management
"Show all teams" → uses pylon_get_teams
"Get account details" → uses pylon_get_accounts

API Reference

For more information about the Pylon API, visit the API reference.