Troubleshooting Guide

This guide covers common issues you may encounter when using the PagerDuty MCP server and how to resolve them.

Authentication Errors

Invalid API Token

Error message:

Authentication failed: Invalid API token

Causes and solutions:

Token not set or incorrect

Check your configuration:VS Code/Cursor:

"env": {
  "PAGERDUTY_USER_API_KEY": "${input:pagerduty-api-key}"
}

Claude Desktop:

"env": {
  "PAGERDUTY_USER_API_KEY": "your-actual-token-here"
}

Verify token:

Go to PagerDuty > My Profile > User Settings > API Access
Ensure token exists and hasn’t been deleted
Create a new token if needed

Token expired or revoked

User API Tokens don’t expire automatically, but they can be revoked:

Check if the token still exists in PagerDuty
If revoked, create a new token
Update your MCP server configuration
Restart the MCP server or client

Environment variable not set

When running locally with uv:

# Check if environment variable is set
echo $PAGERDUTY_USER_API_KEY

# Set it temporarily
export PAGERDUTY_USER_API_KEY="your-token-here"

# Or use .env file
echo "PAGERDUTY_USER_API_KEY=your-token-here" > .env

Wrong API Region

Error message:

Authentication failed or Connection refused

Solution: If your PagerDuty account is in the EU region, you must set the correct API host:

"env": {
  "PAGERDUTY_USER_API_KEY": "your-token-here",
  "PAGERDUTY_API_HOST": "https://api.eu.pagerduty.com"
}

How to verify your region:

Log into PagerDuty
Check the URL: app.pagerduty.com (US) or app.eu.pagerduty.com (EU)
Set PAGERDUTY_API_HOST accordingly

Insufficient Permissions

Error message:

Access denied: Insufficient permissions

Cause: Your user role doesn’t have permission for the requested operation. Solutions:

Check your user role: Go to PagerDuty > My Profile to see your role
Required roles for common operations:
- Read operations: All roles (Responder, Manager, Admin, Owner)
- Create incidents: Responder or higher
- Modify schedules: Manager or higher
- Update services: Manager or higher
- Manage teams: Admin or higher
Request elevated permissions: Contact your PagerDuty admin if you need higher access
Use appropriate token: Ensure the token is from a user with sufficient permissions

Connection Issues

Cannot Connect to PagerDuty API

Error message:

Connection error: Unable to reach api.pagerduty.com

Troubleshooting steps:

Check internet connectivity

# Test basic connectivity
ping api.pagerduty.com

# Test HTTPS connectivity
curl -I https://api.pagerduty.com

Verify DNS resolution

# Check DNS lookup
nslookup api.pagerduty.com

# Or with dig
dig api.pagerduty.com

Check firewall/proxy

Ensure outbound HTTPS (port 443) is allowed
If behind a corporate proxy, configure proxy settings
Check if VPN is required for external API access

Test API directly

curl -H "Authorization: Token token=your-token-here" \
  https://api.pagerduty.com/users/me

If this works, the issue is with the MCP server configuration.

SSL/TLS Certificate Errors

Error message:

SSL certificate verification failed

Causes:

Corporate proxy with SSL inspection
Outdated system certificates
System clock incorrect

Solutions:

Update system certificates:

# Ubuntu/Debian
sudo apt-get update
sudo apt-get install ca-certificates

# macOS
# Certificates are managed by Keychain Access
# Update macOS to latest version

Check system time:

date
# Ensure date/time is correct
# SSL certificates are time-sensitive

Corporate proxy: Contact your IT department for proxy certificate configuration

Never disable SSL certificate verification in production environments.

Tool Invocation Errors

Missing Required Parameters

Error message:

Validation error: Missing required parameter 'incident_id'

Solution: Provide all required parameters when using tools. Check the tool documentation:

Example:

# ❌ Incorrect - missing incident ID
Show incident details

# ✅ Correct - includes incident ID
Show details for incident INC-1234

Invalid Parameter Values

Error message:

Validation error: Invalid value for 'status': must be one of [triggered, acknowledged, resolved]

Solution: Check that parameter values match the expected format: Common parameters and valid values:

Status: triggered, acknowledged, resolved
Urgency: high, low
Event action: trigger, resolve, acknowledge, suppress
Date/time: ISO 8601 format (e.g., 2026-03-10T14:30:00Z)
IDs: Format varies by resource type:
- Incidents: INC-#### or just the numeric ID
- Users: P###### format
- Services: SVC#### format (varies)
- Schedules: SCHED#### format (varies)

Resource Not Found

Error message:

Resource not found: Incident INC-9999 does not exist

Troubleshooting:

Verify the ID:
- Check for typos in the ID
- Ensure you’re using the correct ID type
- Some resources use numeric IDs, others use prefixes
Check access permissions:
- You may not have permission to view the resource
- Resource might be in a team you’re not part of
Confirm resource exists:
- Resource may have been deleted
- Use list operations to find valid IDs

List available resources:

# List incidents to find correct ID
List all incidents

# List services
Show all services

# List schedules
List schedules

Write Operations Disabled

Error message:

Operation not permitted: Write tools are not enabled

Solution: Write operations require the --enable-write-tools flag: VS Code/Cursor:

"args": [
  "pagerduty-mcp",
  "--enable-write-tools"
]

Claude Desktop:

"args": [
  "pagerduty-mcp",
  "--enable-write-tools"
]

Local development:

uv run --directory /path/to/mcp-server python -m pagerduty_mcp --enable-write-tools

Only enable write tools when you need to modify PagerDuty data. See Security Best Practices for guidance.

MCP Server Startup Issues

Server Won’t Start

Symptoms:

MCP server doesn’t appear in client
Client shows “Server not available”
No response from MCP tools

Troubleshooting:

Check Python version

The server requires Python 3.12:

python --version
# Should show Python 3.12.x

If using asdf:

asdf current python
asdf install python 3.12.0
asdf global python 3.12.0

Verify uv installation

# Check if uv is installed
uv --version

# If not installed
curl -LsSf https://astral.sh/uv/install.sh | sh

Check package installation

For uvx (recommended):

# Test if package is accessible
uvx pagerduty-mcp --help

For local development:

cd /path/to/pagerduty-mcp
uv sync
uv run python -m pagerduty_mcp --help

Review client logs

VS Code:

Open Command Palette (Cmd+Shift+P / Ctrl+Shift+P)
Search “MCP: List Servers”
Check server status
View logs for error messages

Claude Desktop: Check logs at:

macOS: ~/Library/Logs/Claude/mcp*.log
Windows: %APPDATA%\Claude\logs\mcp*.log

Restart the client

Sometimes a simple restart resolves startup issues:

VS Code/Cursor: Restart the application completely
Claude Desktop: Quit and relaunch (not just closing windows)

Module Import Errors

Error message:

ModuleNotFoundError: No module named 'pagerduty_mcp'

Solution:

For uvx installations:

# Clear uvx cache and reinstall
uvx --refresh pagerduty-mcp --help

For local development:
```
cd /path/to/pagerduty-mcp
uv sync
```
Verify package is installed:
```
uv pip list | grep pagerduty
```

Docker-Specific Issues

Docker Image Won’t Build

Error during build: Check Docker is running:

docker --version
docker ps

Build the image:

cd /path/to/pagerduty-mcp
docker build -t pagerduty-mcp:latest .

Container Exits Immediately

Container starts then stops: Check logs:

docker logs <container-id>

Common causes:

Missing environment variables
Invalid API token
Incorrect command arguments

Correct Docker run command:

docker run -i --rm \
  -e PAGERDUTY_USER_API_KEY="your-token" \
  pagerduty-mcp:latest

Note the -i flag (interactive) is required for stdio transport.

Debugging Techniques

Enable Verbose Logging

For local development, run with debugging enabled:

# Set log level
export MCP_LOG_LEVEL=DEBUG

# Run server
uv run python -m pagerduty_mcp --enable-write-tools

Test Tools Manually

You can test tools directly using the MCP inspector:

# Install MCP inspector
npm install -g @modelcontextprotocol/inspector

# Run inspector
mcp-inspector uvx pagerduty-mcp

This opens a web interface to test tools without an AI client.

Verify API Connectivity

Test the PagerDuty API directly:

# Get your user information
curl -H "Authorization: Token token=YOUR_TOKEN" \
  -H "Accept: application/vnd.pagerduty+json;version=2" \
  https://api.pagerduty.com/users/me

# List incidents
curl -H "Authorization: Token token=YOUR_TOKEN" \
  -H "Accept: application/vnd.pagerduty+json;version=2" \
  https://api.pagerduty.com/incidents

If these work but the MCP server doesn’t, the issue is with the server configuration.

Check Server Health

For local development:

# Run tests
cd /path/to/pagerduty-mcp
uv run pytest tests/

# Run evals
uv run python tests/evals/run_tests.py

Getting Help

Before Asking for Help

Gather this information:

Version information:

uvx pagerduty-mcp --version
python --version
uv --version

Configuration (with tokens redacted):
- Your MCP client configuration
- Environment variables being set
- Command-line arguments
Error messages:
- Complete error output
- Client logs
- Server logs if available
Steps to reproduce:
- What you’re trying to do
- Commands or queries you’re using
- Expected vs actual behavior

Where to Get Help

GitHub Issues

Report bugs and request features

Community Forum

Ask questions and share solutions

Security Issues

Report security vulnerabilities

Contributing

Contribute fixes and improvements

Usage Patterns

Support

Authentication Errors

Invalid API Token

Wrong API Region

Insufficient Permissions

Connection Issues

Cannot Connect to PagerDuty API

SSL/TLS Certificate Errors

Tool Invocation Errors

Missing Required Parameters

Invalid Parameter Values

Resource Not Found

Write Operations Disabled

MCP Server Startup Issues

Server Won’t Start

Module Import Errors

Docker-Specific Issues

Docker Image Won’t Build

Container Exits Immediately

Debugging Techniques

Enable Verbose Logging

Test Tools Manually

Verify API Connectivity

Check Server Health

Getting Help

Before Asking for Help

Where to Get Help

GitHub Issues

Community Forum

Security Issues

Contributing

Build docs developers (and LLMs) love

Usage Patterns

Support

​Authentication Errors

​Invalid API Token

​Wrong API Region

​Insufficient Permissions

​Connection Issues

​Cannot Connect to PagerDuty API

​SSL/TLS Certificate Errors

​Tool Invocation Errors

​Missing Required Parameters

​Invalid Parameter Values

​Resource Not Found

​Write Operations Disabled

​MCP Server Startup Issues

​Server Won’t Start

​Module Import Errors

​Docker-Specific Issues

​Docker Image Won’t Build

​Container Exits Immediately

​Debugging Techniques

​Enable Verbose Logging

​Test Tools Manually

​Verify API Connectivity

​Check Server Health

​Getting Help

​Before Asking for Help

​Where to Get Help

GitHub Issues

Community Forum

Security Issues

Contributing

​Related Resources

Build docs developers (and LLMs) love

Authentication Errors

Invalid API Token

Wrong API Region

Insufficient Permissions

Connection Issues

Cannot Connect to PagerDuty API

SSL/TLS Certificate Errors

Tool Invocation Errors

Missing Required Parameters

Invalid Parameter Values

Resource Not Found

Write Operations Disabled

MCP Server Startup Issues

Server Won’t Start

Module Import Errors

Docker-Specific Issues

Docker Image Won’t Build

Container Exits Immediately

Debugging Techniques

Enable Verbose Logging

Test Tools Manually

Verify API Connectivity

Check Server Health

Getting Help

Before Asking for Help

Where to Get Help

Related Resources