Security Best Practices

​

API Token Management

​

Obtaining a User API Token

1. Navigate to My Profile > User Settings in PagerDuty
2. Locate the API Access section
3. Click Create API User Token
4. Copy the token immediately (it won’t be shown again)
5. Store it securely

​

Token Permissions

• Responder role: Read-only access to most resources
• Manager role: Can modify teams and schedules
• Admin role: Full account access
• Account Owner role: Complete control including billing

​

Secure Token Storage

​

Local Development

{
  "mcp": {
    "inputs": [
      {
        "type": "promptString",
        "id": "pagerduty-api-key",
        "description": "PagerDuty API Key",
        "password": true
      }
    ],
    "servers": {
      "pagerduty-mcp": {
        "env": {
          "PAGERDUTY_USER_API_KEY": "${input:pagerduty-api-key}"
        }
      }
    }
  }
}

{
  "mcpServers": {
    "pagerduty-mcp": {
      "env": {
        "PAGERDUTY_USER_API_KEY": "your-token-here"
      }
    }
  }
}

​

Production Deployments

1. Use environment variables: Never hardcode tokens in configuration files
2. Use secrets management: Store tokens in tools like:
   • AWS Secrets Manager
   • HashiCorp Vault
   • Kubernetes Secrets
   • Cloud provider secret services
3. Rotate regularly: Change tokens periodically and after any suspected compromise
4. Audit token usage: Review which tokens are active and revoke unused ones

​

Token Rotation

1. Create a new User API Token in PagerDuty
2. Update your MCP server configuration with the new token
3. Test that the server works with the new token
4. Delete the old token from PagerDuty

​

Read-Only vs Write Mode

​

Understanding the Modes

• Only tools that retrieve information are available
• Cannot create, modify, or delete resources
• Safer for exploration and read-only integrations
• Suitable for reporting and monitoring use cases

• All tools are available, including those that modify data
• Can create incidents, schedule overrides, update services, etc.
• Required for automation and incident response
• Higher risk of accidental or unauthorized changes

​

Choosing the Right Mode

​

Enabling Write Mode Safely

1. Understand the risks: Write operations can:
   • Create incidents (triggering on-call notifications)
   • Modify schedules (affecting on-call coverage)
   • Change escalation policies (altering incident routing)
   • Delete resources (potential data loss)
2. Use in controlled environments: Enable only when:
   • You trust the AI assistant’s behavior
   • You understand what operations will be performed
   • You can undo changes if needed
3. Start with read-only: Test your workflows in read-only mode first
4. Review AI suggestions: Always review what the AI plans to do before confirming write operations

​

Client Configuration Security

​

Regional Endpoints

{
  "PAGERDUTY_API_HOST": "https://api.pagerduty.com"
}

{
  "PAGERDUTY_API_HOST": "https://api.eu.pagerduty.com"
}

​

Network Security

• api.pagerduty.com (US)
• api.eu.pagerduty.com (EU)

• The proxy supports HTTPS
• Certificate validation works correctly
• Proxy logs don’t capture token headers

​

Docker Security

1. Don’t commit images with tokens: Use environment variables, not baked-in tokens
2. Use minimal base images: Smaller images have fewer vulnerabilities
3. Run as non-root: The official image uses a non-root user
4. Scan for vulnerabilities: Regularly scan Docker images
5. Limit container permissions: Use Docker security options like --read-only where possible

​

Audit Logging Recommendations

​

Monitoring API Activity

1. Navigate to Account Settings > Audit Trail in PagerDuty
2. Filter by:
   • API authentication events
   • Resource modifications
   • User performing actions
3. Review logs regularly for:
   • Unexpected API calls
   • Unauthorized access attempts
   • Unusual patterns

​

What to Monitor

​

Least Privilege Principles

​

Creating Dedicated Users

1. Create a dedicated PagerDuty user (e.g., [email protected])
2. Assign minimal required role:
   • Read-only use cases: Responder role
   • Incident management: Manager role
   • Full automation: Admin role (use sparingly)
3. Generate token from dedicated user
4. Document the token’s purpose
5. Set up monitoring for this user’s API activity

​

Restricting Tool Access

• Default configuration
• No --enable-write-tools flag
• Used for dashboards and reporting

• Includes --enable-write-tools flag
• Used only when changes are needed
• Access restricted to authorized personnel

​

Team Access Controls

1. Organize resources by team: Associate services, schedules, and escalation policies with teams
2. Limit user team membership: Users only see resources for their teams
3. Use team-scoped tokens: Tokens only have access to associated teams
4. Review team membership regularly: Remove users who no longer need access

​

Incident Response for Token Compromise

​

Immediate Actions

1. Revoke the token immediately:
   • Go to User Settings > API Access
   • Delete the compromised token
2. Review audit logs:
   • Check for unauthorized API calls
   • Identify what actions were performed
   • Document the timeline
3. Generate a new token:
   • Create a new User API Token
   • Update all configurations using the old token
   • Test the new token works correctly
4. Assess impact:
   • Review incidents created
   • Check for configuration changes
   • Verify schedule integrity
   • Look for data exfiltration

​

Prevention

• Never commit tokens to source control: Use .gitignore for config files
• Don’t share tokens: Each person should have their own
• Avoid logging tokens: Ensure logs don’t capture environment variables
• Use short-lived credentials when possible: Rotate tokens regularly
• Monitor for exposed secrets: Use tools like GitHub Secret Scanning

​

Compliance Considerations

​

Data Privacy

1. Understand data flow: Know where your PagerDuty data goes:
   • AI provider’s servers (OpenAI, Anthropic, etc.)
   • MCP client applications
   • Local storage and caches
2. Review privacy policies: Check if your AI provider:
   • Uses data for training
   • Stores conversation history
   • Shares data with third parties
3. Anonymize sensitive data: Consider redacting:
   • Customer names
   • Personal information
   • Proprietary technical details
   • Internal system names

​

Regulatory Requirements

• SOC 2: Ensure token management meets access control requirements
• HIPAA: Avoid including PHI in incident details visible to the AI
• GDPR: Be aware that PagerDuty data may include personal information
• PCI DSS: Never include payment card data in incident information

​

Related Resources

• Configuration Guide
• Installation Guide
• PagerDuty API Authentication
• PagerDuty Security