Skip to main content

​
MCP API Overview

The Unhook MCP (Model Context Protocol) server provides a standardized interface for AI assistants to access webhook data and debugging tools.

​
Base URL

https://app.unhook.sh/api/mcp

​
Authentication

All requests require authentication using a Bearer token: 
Authorization: Bearer YOUR_API_KEY
Get your API key from https://unhook.sh/app/api-keys.

​
Transport

The MCP server supports HTTP Server-Sent Events (SSE) transport for real-time bidirectional communication.

​
Protocol

The server implements the Model Context Protocol v1.0 specification with JSON-RPC 2.0 messages.

​
Request Format

{
  "jsonrpc": "2.0",
  "id": "unique-request-id",
  "method": "resources/list",
  "params": {}
}

​
Response Format

{
  "jsonrpc": "2.0",
  "id": "unique-request-id",
  "result": {
    "resources": [...]
  }
}

​
Available Methods

​
Resources

​
resources/list
method
Lists all available resourcesResponse:
{
  "resources": [
    {
      "uri": "webhook://events/recent",
      "name": "Recent Webhook Events",
      "description": "Last 100 webhook events"
    },
    {
      "uri": "webhook://requests/recent",
      "name": "Recent Webhook Requests",
      "description": "Last 100 webhook requests"
    },
    {
      "uri": "webhook://webhooks/list",
      "name": "Webhook List",
      "description": "All configured webhooks"
    }
  ]
}
​
resources/read
method
Reads a specific resourceParameters:
  • uri (string, required): Resource URI to read
Example Request:
{
  "method": "resources/read",
  "params": {
    "uri": "webhook://events/recent"
  }
}

​
Tools

​
tools/list
method
Lists all available toolsResponse includes:
  • search_events - Search webhook events
  • search_requests - Search webhook requests
  • analyze_event - Analyze specific event
  • analyze_request - Analyze specific request
  • get_webhook_stats - Get webhook statistics
​
tools/call
method
Executes a tool with parametersParameters:
  • name (string, required): Tool name
  • arguments (object, required): Tool-specific arguments
Example Request:
{
  "method": "tools/call",
  "params": {
    "name": "search_events",
    "arguments": {
      "webhookId": "wh_123",
      "status": "failed",
      "limit": 50
    }
  }
}

​
Prompts

​
prompts/list
method
Lists all available promptsResponse includes:
  • debug_webhook_issue - Debugging workflow
  • analyze_failures - Failure analysis
  • performance_report - Performance analysis
​
prompts/get
method
Gets a specific prompt templateParameters:
  • name (string, required): Prompt name
Response:
{
  "name": "debug_webhook_issue",
  "description": "Help debug webhook issues",
  "arguments": [
    {
      "name": "webhookId",
      "description": "ID of the webhook to debug",
      "required": true
    }
  ]
}

​
Rate Limits

  • Requests per minute: 60
  • Concurrent connections: 5
  • Response size: 10MB max

​
Error Handling

Errors follow the JSON-RPC 2.0 error format: 
{
  "jsonrpc": "2.0",
  "id": "request-id",
  "error": {
    "code": -32602,
    "message": "Invalid params",
    "data": {
      "details": "Missing required parameter: webhookId"
    }
  }
}

​
Common Error Codes

CodeMessageDescription
-32700Parse errorInvalid JSON
-32600Invalid requestInvalid JSON-RPC
-32601Method not foundUnknown method
-32602Invalid paramsInvalid parameters
-32603Internal errorServer error
401UnauthorizedInvalid or missing API key
429Too Many RequestsRate limit exceeded

​
Example Session

# Initialize connection
curl -X POST https://app.unhook.sh/api/mcp \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":"1","method":"initialize","params":{"protocolVersion":"1.0.0","capabilities":{}}}'

# List resources
curl -X POST https://app.unhook.sh/api/mcp/message \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":"2","method":"resources/list","params":{}}'

# Read events
curl -X POST https://app.unhook.sh/api/mcp/message \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":"3","method":"resources/read","params":{"uri":"webhook://events/recent"}}'

​
SDK Support

The MCP server is compatible with:

​
Webhooks Integration

The MCP server automatically scopes data access to your organization based on the API key. You can only access webhooks, events, and requests that belong to your organization.

​
Next Steps

⌘I