Unhook MCP Server

Use Unhook’s webhook data through the Model Context Protocol

A Model Context Protocol (MCP) server implementation that integrates Unhook for webhook debugging and analysis capabilities. Our MCP server provides access to your webhook events, requests, and analytics through AI assistants like Claude and Cursor.

Features

Webhook event monitoring and analysis
Request inspection and debugging
Performance metrics and failure analysis
Real-time webhook data access
Cloud and self-hosted support
SSE transport support

Installation

You can either use our remote hosted URL or run the server locally. Get your API key from your Unhook dashboard at https://unhook.sh/app/api-keys.

Remote hosted URL

https://unhook.sh/api/mcp/{YOUR_API_KEY}/sse

Running with npx

env UNHOOK_API_KEY=your-api-key npx -y @unhook/mcp-server

Manual Installation

npm install -g @unhook/mcp-server

Try out our MCP Server on MCP.so’s playground or integrate with your favorite AI assistant.

Configuration

Environment Variables

Required for Cloud API

UNHOOK_API_KEY: Your Unhook API key
- Required when using cloud API (default)
- Get this from https://unhook.sh/app/api-keys
UNHOOK_API_URL (Optional): Custom API endpoint for self-hosted instances
- Example: https://api.your-domain.com
- If not provided, the cloud API will be used (requires API key)

Optional Configuration

Retry Configuration

UNHOOK_RETRY_MAX_ATTEMPTS: Maximum number of retry attempts (default: 3)
UNHOOK_RETRY_INITIAL_DELAY: Initial delay in milliseconds before first retry (default: 1000)
UNHOOK_RETRY_MAX_DELAY: Maximum delay in milliseconds between retries (default: 10000)
UNHOOK_RETRY_BACKOFF_FACTOR: Exponential backoff multiplier (default: 2)

Rate Limiting

UNHOOK_RATE_LIMIT_REQUESTS: Maximum requests per minute (default: 60)
UNHOOK_RATE_LIMIT_WINDOW: Rate limit window in milliseconds (default: 60000)

Configuration Examples

Basic Cloud Configuration

{
  "mcpServers": {
    "unhook": {
      "url": "https://unhook.sh/api/mcp/YOUR_API_KEY/sse",
      "transport": "sse"
    }
  }
}

Self-Hosted Configuration

{
  "mcpServers": {
    "unhook": {
      "command": "npx",
      "args": ["-y", "@unhook/mcp-server"],
      "env": {
        "UNHOOK_API_KEY": "your-api-key",
        "UNHOOK_API_URL": "https://api.your-domain.com"
      }
    }
  }
}

Running on Different Platforms

Running on Cursor

Add Unhook MCP server to Cursor

Manual Installation

Note: Requires Cursor version 0.45.6+

To configure Unhook MCP in Cursor v0.48.6:

Open Cursor Settings
Go to Features > MCP Servers
Click ”+ Add new global MCP server”
Enter the following code:

{
  "mcpServers": {
    "unhook": {
      "command": "npx",
      "args": ["-y", "@unhook/mcp-server"],
      "env": {
        "UNHOOK_API_KEY": "YOUR-API-KEY"
      }
    }
  }
}

To configure Unhook MCP in Cursor v0.45.6:

Open Cursor Settings
Go to Features > MCP Servers
Click ”+ Add New MCP Server”
Enter the following:
- Name: “unhook” (or your preferred name)
- Type: “command”
- Command: env UNHOOK_API_KEY=your-api-key npx -y @unhook/mcp-server

If you are using Windows and are running into issues, try cmd /c "set UNHOOK_API_KEY=your-api-key && npx -y @unhook/mcp-server"

Replace your-api-key with your Unhook API key. If you don’t have one yet, you can get it from https://unhook.sh/app/api-keys.

After adding, refresh the MCP server list to see the new tools. The Composer Agent will automatically use Unhook MCP when appropriate, but you can explicitly request it by describing your webhook debugging needs.

Running on Windsurf

Add this to your ./codeium/windsurf/model_config.json:

{
  "mcpServers": {
    "mcp-server-unhook": {
      "command": "npx",
      "args": ["-y", "@unhook/mcp-server"],
      "env": {
        "UNHOOK_API_KEY": "YOUR_API_KEY"
      }
    }
  }
}

Running with SSE Mode

To run the server using Server-Sent Events (SSE) locally instead of the default stdio transport:

env SSE_LOCAL=true UNHOOK_API_KEY=your-api-key npx -y @unhook/mcp-server

Use the url: http://localhost:3000/sse or https://unhook.sh/api/mcp/{YOUR_API_KEY}/sse

Running on VS Code

For manual installation, add the following JSON block to your User Settings (JSON) file in VS Code. You can do this by pressing Ctrl + Shift + P and typing Preferences: Open User Settings (JSON).

{
  "mcp": {
    "inputs": [
      {
        "type": "promptString",
        "id": "apiKey",
        "description": "Unhook API Key",
        "password": true
      }
    ],
    "servers": {
      "unhook": {
        "command": "npx",
        "args": ["-y", "@unhook/mcp-server"],
        "env": {
          "UNHOOK_API_KEY": "${input:apiKey}"
        }
      }
    }
  }
}

Optionally, you can add it to a file called .vscode/mcp.json in your workspace. This will allow you to share the configuration with others:

{
  "inputs": [
    {
      "type": "promptString",
      "id": "apiKey",
      "description": "Unhook API Key",
      "password": true
    }
  ],
  "servers": {
    "unhook": {
      "command": "npx",
      "args": ["-y", "@unhook/mcp-server"],
      "env": {
        "UNHOOK_API_KEY": "${input:apiKey}"
      }
    }
  }
}

Running on Claude Desktop

Add this to the Claude config file:

{
  "mcpServers": {
    "unhook": {
      "url": "https://unhook.sh/api/mcp/{YOUR_API_KEY}/sse"
    }
  }
}

Rate Limiting and Performance

The server utilizes Unhook’s built-in rate limiting and performance optimization:

Automatic rate limit handling with exponential backoff
Efficient data pagination for large datasets
Smart request caching and deduplication
Automatic retries for transient errors

Available Tools

1. Search Events Tool (`search_events`)

Search webhook events with advanced filtering options.

{
  "name": "search_events",
  "arguments": {
    "webhookId": "wh_123",
    "status": "failed",
    "limit": 50,
    "startDate": "2024-01-01T00:00:00Z",
    "endDate": "2024-01-31T23:59:59Z",
    "source": "stripe"
  }
}

2. Search Requests Tool (`search_requests`)

Search webhook requests with detailed filtering.

{
  "name": "search_requests",
  "arguments": {
    "webhookId": "wh_123",
    "status": "failed",
    "limit": 50,
    "minResponseTime": 1000,
    "maxResponseTime": 5000
  }
}

3. Analyze Event Tool (`analyze_event`)

Get detailed analysis of a specific webhook event.

{
  "name": "analyze_event",
  "arguments": {
    "eventId": "evt_123"
  }
}

4. Analyze Request Tool (`analyze_request`)

Get detailed analysis of a specific webhook request.

{
  "name": "analyze_request",
  "arguments": {
    "requestId": "req_123"
  }
}

5. Get Webhook Stats Tool (`get_webhook_stats`)

Get comprehensive statistics for webhooks.

{
  "name": "get_webhook_stats",
  "arguments": {
    "webhookId": "wh_123",
    "timeRange": "24h",
    "includeFailures": true,
    "includePerformance": true
  }
}

6. Create Test Event Tool (`create_test_event`)

Create a test webhook event for debugging.

{
  "name": "create_test_event",
  "arguments": {
    "webhookId": "wh_123",
    "payload": {
      "test": "data",
      "timestamp": "2024-01-01T00:00:00Z"
    },
    "headers": {
      "Content-Type": "application/json",
      "X-Test-Header": "test-value"
    }
  }
}

7. Debug Webhook Issue Tool (`debug_webhook_issue`)

Get intelligent debugging assistance for webhook issues.

{
  "name": "debug_webhook_issue",
  "arguments": {
    "webhookId": "wh_123",
    "issueType": "failures",
    "timeRange": "1h",
    "includeRecommendations": true
  }
}

8. Performance Report Tool (`performance_report`)

Generate comprehensive performance reports.

{
  "name": "performance_report",
  "arguments": {
    "webhookIds": ["wh_123", "wh_456"],
    "timeRange": "7d",
    "includeTrends": true,
    "includeRecommendations": true
  }
}

Available Resources

Recent Events (`webhook://events/recent`)

Access the most recent webhook events with metadata.

Recent Requests (`webhook://requests/recent`)

Access the most recent webhook requests with response data.

Webhook List (`webhook://webhooks/list`)

Get all configured webhooks in your organization.

Active Connections (`webhook://connections/active`)

View currently active webhook connections.

Statistics Overview (`webhook://stats/overview`)

Get high-level statistics for all webhooks.

Logging System

The server includes comprehensive logging:

Connection status and authentication
Request/response performance metrics
Error conditions and retry attempts
Rate limit tracking

Example log messages:

[INFO] Unhook MCP Server initialized successfully
[INFO] Connected to webhook wh_123
[INFO] Retrieved 50 events for analysis
[WARNING] Rate limit approaching, throttling requests
[ERROR] Authentication failed, retrying in 2s...

Error Handling

The server provides robust error handling:

Automatic retries for transient errors
Rate limit handling with backoff
Detailed error messages with context
Authentication error recovery
Network resilience

Example error response:

{
  "content": [
    {
      "type": "text",
      "text": "Error: Rate limit exceeded. Retrying in 2 seconds..."
    }
  ],
  "isError": true
}

Usage Examples

Debugging Failed Webhooks

Ask your AI assistant:

“Show me all failed webhook events from the last hour”
“Why are my Stripe webhooks failing?”
“Analyze the error patterns in my webhook requests”

Performance Analysis

Ask your AI assistant:

“What’s the average response time for my webhooks?”
“Which webhooks have the highest failure rate?”
“Generate a performance report for my payment webhooks”

Request Inspection

Ask your AI assistant:

“Show me the payload for event evt_123”
“What headers were sent with the last GitHub webhook?”
“Compare successful vs failed requests for my Clerk webhook”

Security

Authentication

All MCP requests require authentication via your Unhook API key
API keys are scoped to your organization’s data only
Never share your API key publicly

Data Access

MCP servers can only access data you have permission to view
All data transmission is encrypted over HTTPS
No webhook data is stored by the AI assistant

Best Practices

Use environment-specific API keys for development vs production
Rotate your API keys regularly
Review MCP access logs in your dashboard

Troubleshooting

Connection Issues

AI assistant can't connect to Unhook

No webhook data appearing

Authentication errors

Rate limiting issues

Performance

The MCP server limits responses to prevent overwhelming AI assistants:

Events: Maximum 100 per request
Requests: Maximum 100 per request
Use search filters to find specific data
Enable pagination for large datasets

Development

# Install dependencies
npm install

# Build
npm run build

# Run tests
npm test

Contributing

Fork the repository
Create your feature branch
Run tests: npm test
Submit a pull request

Support

Need help with MCP integration?

Check our GitHub discussions
Join our Discord community
Email support at support@unhook.sh

License

MIT License - see LICENSE file for details

Get Started

Reference

Solutions

Development

​Unhook MCP Server

​Features

​Installation

​Remote hosted URL

​Running with npx

​Manual Installation

​Configuration

​Environment Variables

​Required for Cloud API

​Optional Configuration

Retry Configuration

Rate Limiting

​Configuration Examples

​Basic Cloud Configuration

​Self-Hosted Configuration

​Running on Different Platforms

​Running on Cursor

​Manual Installation

​Running on Windsurf

​Running with SSE Mode

​Running on VS Code

​Running on Claude Desktop

​Rate Limiting and Performance

​Available Tools

​1. Search Events Tool (search_events)

​2. Search Requests Tool (search_requests)

​3. Analyze Event Tool (analyze_event)

​4. Analyze Request Tool (analyze_request)

​5. Get Webhook Stats Tool (get_webhook_stats)

​6. Create Test Event Tool (create_test_event)

​7. Debug Webhook Issue Tool (debug_webhook_issue)

​8. Performance Report Tool (performance_report)

​Available Resources

​Recent Events (webhook://events/recent)

​Recent Requests (webhook://requests/recent)

​Webhook List (webhook://webhooks/list)

​Active Connections (webhook://connections/active)

​Statistics Overview (webhook://stats/overview)

​Logging System

​Error Handling

​Usage Examples

​Debugging Failed Webhooks

​Performance Analysis

​Request Inspection

​Security

​Authentication

​Data Access

​Best Practices

​Troubleshooting

​Connection Issues

​Performance

​Development

​Contributing

​Support

​License

Unhook MCP Server

Features

Installation

Remote hosted URL

Running with npx

Manual Installation

Configuration

Environment Variables

Required for Cloud API

Optional Configuration

Configuration Examples

Basic Cloud Configuration

Self-Hosted Configuration

Running on Different Platforms

Running on Cursor

Manual Installation

Running on Windsurf

Running with SSE Mode

Running on VS Code

Running on Claude Desktop

Rate Limiting and Performance

Available Tools

1. Search Events Tool (`search_events`)

2. Search Requests Tool (`search_requests`)

3. Analyze Event Tool (`analyze_event`)

4. Analyze Request Tool (`analyze_request`)

5. Get Webhook Stats Tool (`get_webhook_stats`)

6. Create Test Event Tool (`create_test_event`)

7. Debug Webhook Issue Tool (`debug_webhook_issue`)

8. Performance Report Tool (`performance_report`)

Available Resources

Recent Events (`webhook://events/recent`)

Recent Requests (`webhook://requests/recent`)

Webhook List (`webhook://webhooks/list`)

Active Connections (`webhook://connections/active`)

Statistics Overview (`webhook://stats/overview`)

Logging System

Error Handling

Usage Examples

Debugging Failed Webhooks

Performance Analysis

Request Inspection

Security

Authentication

Data Access

Best Practices

Troubleshooting

Connection Issues

Performance

Development

Contributing

Support

License