Pylon MCP Server

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

Features

This MCP server provides tools to interact with Pylon's API:

• User Management: Get current user information
• Contacts: List, search, and create contacts
• Issues: List, filter, and create issues
• Knowledge Base: Access and create knowledge base articles
• Smart Caching: Automatic caching of GET requests to minimize API usage

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

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)

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/publish.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)
• ✅ Contact Management (get, search, create)
• ✅ Message Management (get messages with attachments)
• ✅ Error Handling (404, network errors)

Available Tools

User Tools

• pylon_get_me: Get current user information

Contact Tools

• pylon_get_contacts: List contacts with optional search and limit
• pylon_create_contact: Create a new contact

Issue Tools

• pylon_get_issues: List issues with optional filtering by assignee, status, and limit
• pylon_create_issue: Create a new issue
• pylon_get_issue: Get details of a specific issue
• pylon_get_issue_with_messages: NEW - 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, etc.
• pylon_snooze_issue: Temporarily hide an issue until a future date

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

Knowledge Base Tools

• pylon_get_knowledge_bases: List all knowledge bases
• pylon_create_knowledge_base_article: Create a new article in a knowledge base

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

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

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

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

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 "[email protected]"

Running via Smithery

1. Deploy to Smithery:

   • Upload your project to Smithery
   • Smithery will automatically use the smithery.yaml configuration
   • Set the PYLON_API_TOKEN environment variable in Smithery's deployment settings

2. Configure in Claude Desktop:

{
  "mcpServers": {
    "pylon": {
      "command": "npx",
      "args": ["-y", "@smithery/pylon-mcp-server"]
    }
  }
}

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

# 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

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

Deployment to Smithery

This server is designed to be deployed to Smithery using the included smithery.yaml configuration. The deployment will automatically:

• Install dependencies with npm install && npm run build
• Configure the Node.js runtime with proper entrypoint
• Expose all supported Pylon API tools
• Require the PYLON_API_TOKEN environment variable

API Reference

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