@customer-support-success/pylon-mcp-server

v3.7.1

Published

a month ago

MCP server for Pylon API integration

0High
0Medium
0Low

mgmonteleone

mcp pylon api integration

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)

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:

Your network connection
Pylon API status
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

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)

Open Augment Settings:
- In VS Code: Open the Augment Code extension settings
- In JetBrains: Navigate to Augment settings
Navigate to Easy MCP:
- Find the "Easy MCP" pane in the settings
- Click the "+" button to add a new MCP server

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"
    }
  }
}

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

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

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

Configure Claude Desktop:

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