incident-io-mcp-server by ianchesal - MCP Server

incident-io-mcp-server

An MCP (Model Context Protocol) server for integrating with incident.io API. This server provides tools for incident management, user lookup, and workflow automation through Claude and other MCP-compatible AI assistants.

⚠️ Security Warning

🚨 DO NOT RUN THIS SERVER ON THE OPEN INTERNET 🚨

This MCP server provides NO AUTHENTICATION on its tool APIs. Anyone who can reach the server can:

List all incidents in your organization
View sensitive incident details
Create new incidents
Access user information
View organizational data (severities, statuses)

Safe Usage:

✅ Run only on localhost/127.0.0.1
✅ Use in local development environments
✅ Deploy behind proper authentication/VPN
❌ Never expose directly to the internet
❌ Never run on public cloud instances without proper network security

This server is designed for local development and secure, authenticated environments only.

Features

Incident Management: List, view, and create incidents
User Lookup: Search and list organization users
Metadata Access: Get incident severities and statuses
Secure Authentication: Bearer token authentication with incident.io API
Comprehensive Testing: Full test suite with async support
Container Runtime Flexibility: Automatic detection and support for both Docker and Podman

Authentication

This MCP server uses Bearer token authentication with the incident.io API. All API requests include an Authorization: Bearer <YOUR_API_KEY> header for secure authentication.

The server supports multiple secure methods for providing your API key and automatically loads environment variables from .env files for development convenience.

Quick Start

Prerequisites

Container Runtime: Docker or Podman (automatically detected)
Compose: docker compose or podman compose
Make: Usually pre-installed on macOS/Linux
API Key: incident.io API key

Development Environment Setup

Clone the repository:

git clone git@github.com:ianchesal/incident-io-mcp-server.git
cd incident-io-mcp-server

Check container runtime and build:
```
make runtime-info  # See which runtime is detected (docker/podman)
make build         # Build all containers
```
Note: The Makefile automatically detects whether you have Docker or Podman installed and uses the appropriate commands. Podman is preferred over Docker if both are available.
Configure your incident.io API key securely:

First, obtain your API key from the incident.io dashboard.

🔐 Secure Configuration Options (choose one):

Option A: Environment Variable (Recommended for production)
```
export INCIDENT_IO_API_KEY="your_incident_io_api_key_here"
```
Option B: .env File (Recommended for development)
```
# Copy the example file and edit with your API key
cp .env.example .env
# Then edit .env with your actual API key
```
Option C: Runtime Environment Variable
```
# Set the API key when running the server
INCIDENT_IO_API_KEY="your_api_key" python -m src.incident_io_mcp.server
```
⚠️ Security Best Practices:
- Never commit API keys to version control
- Use environment variables in production environments
- Rotate API keys regularly
- Use the principle of least privilege - create API keys with only the permissions needed
- Store API keys securely using your organization's secret management system

Running the MCP Server

Option 1: Run the MCP server (recommended):

make up

Option 2: Run in detached mode:

make up-d

Option 3: Run with custom environment:

INCIDENT_IO_API_KEY=your_api_key make up

The server will start and listen for MCP connections. You can then connect it to Claude Desktop or other MCP-compatible clients.

Development Workflow

Start development environment:

make dev

Open development shell:

make shell

Run commands inside the container:

# Inside the development container
python -m src.incident_io_mcp.server  # Run the server
pytest                                # Run tests
python -c "import src.incident_io_mcp.server; print('Import successful')"  # Test imports

Stop development containers:

make down-dev

Running Tests

Run all tests:

make test

Run tests with coverage:

make test-cov

Run specific test file:

make test-file FILE=test_server.py

Run tests interactively in development container:

make dev
make shell
# Inside container:
pytest -v

Debugging

Access logs:

make logs      # Show logs
make logs-f    # Follow logs

Interactive debugging:

# Start development environment and open shell
make dev
make shell

# Inside container - run with debugger
python -m pdb -m src.incident_io_mcp.server

Available Make Commands

Run make help to see all available commands:

make help

Core commands:

make runtime-info - Show detected container runtime (docker/podman)
make build - Build all containers
make up - Start MCP server
make up-d - Start MCP server in detached mode
make dev - Start development environment
make shell - Open development shell

Testing and Quality:

make test - Run all tests
make test-cov - Run tests with coverage report
make test-file FILE=test_server.py - Run specific test file
make typecheck - Run type checking with mypy
make lint - Run code linting with flake8
make security - Run security checks with bandit and safety

Utility:

make logs - View server logs
make logs-f - Follow server logs
make down - Stop all services
make down-dev - Stop development profile
make clean - Stop and remove all containers
make clean-deep - Deep clean: remove all containers, images, volumes, and build cache