MCP API Overview

Model Context Protocol API endpoints and specifications

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 resources

Response:

{
  "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 resource

Parameters:

• uri (string, required): Resource URI to read

Example Request:

{
  "method": "resources/read",
  "params": {
    "uri": "webhook://events/recent"
  }
}

Tools

tools/list · method

Lists all available tools

Response 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 parameters

Parameters:

• 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 prompts

Response includes:

• debug_webhook_issue - Debugging workflow
• analyze_failures - Failure analysis
• performance_report - Performance analysis

prompts/get · method

Gets a specific prompt template

Parameters:

• 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

Code	Message	Description
-32700	Parse error	Invalid JSON
-32600	Invalid request	Invalid JSON-RPC
-32601	Method not found	Unknown method
-32602	Invalid params	Invalid parameters
-32603	Internal error	Server error
401	Unauthorized	Invalid or missing API key
429	Too Many Requests	Rate 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:

• @modelcontextprotocol/typescript-sdk
• Claude Desktop MCP client
• Cursor AI integration

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

• Review the Tool Reference for detailed tool documentation
• Check the Resource Reference for resource schemas
• See Integration Examples for common use cases

Assistant

Responses are generated using AI and may contain mistakes.