---
title: "MCP Server | WebhookRelay"
meta:
  "og:description": "Use the Webhook Relay MCP server to manage buckets, inputs, outputs, webhook logs, transform functions and cloud connections from AI agents."
  "og:title": "MCP Server"
  description: "Use the Webhook Relay MCP server to manage buckets, inputs, outputs, webhook logs, transform functions and cloud connections from AI agents."
---

![Stripes](https://webhookrelay.com/docs/mcp/images/stripes.svg)

Documentation

**Fundamentals**

# **MCP Server**

Use the Webhook Relay MCP server to manage buckets, inputs, outputs, webhook logs, transform functions and cloud connections from AI agents.

## [Overview](#overview)

Webhook Relay provides an MCP (Model Context Protocol) server that lets AI agents manage your webhook infrastructure programmatically.

You can configure and access MCP from:

- [https://my.webhookrelay.com/mcp](https://my.webhookrelay.com/mcp)

> Prefer guiding your agent through the `relay` CLI instead of (or alongside) MCP? See [Agent Skills](https://webhookrelay.com/docs/mcp/docs/skills/).

The MCP API endpoint is:

- `https://my.webhookrelay.com/v1/mcp`

## [Authentication](#authentication)

Authenticate requests with a Bearer token in the `Authorization` header:

```
Authorization: Bearer <token>
```

## [Configure MCP in Webhook Relay](#configure-mcp-in-webhook-relay)

Open the MCP page in your Webhook Relay account and use the provided configuration values in your MCP client or agent:

![Webhook Relay MCP configuration](https://webhookrelay.com/docs/mcp/images/docs/mcp/mcp_config.png)

## [Connect Claude.ai](#connect-claudeai)

You can add Webhook Relay to Claude.ai as a **custom connector** using just the MCP endpoint URL — there is no API key to copy and paste, authentication happens in your browser when you connect.

> Adding custom connectors requires a Claude **Pro, Max, Team, or Enterprise** plan.

1. In Claude.ai, open **Settings → Connectors** (on Team/Enterprise, an admin adds it under **Settings → Connectors → Organization connectors**).
2. Click **Add custom connector**.
3. Fill in the form and click **Add**:
  - **Name**: `webhookrelay`
  - **Remote MCP server URL**:```
https://my.webhookrelay.com/v1/mcp
```
4. Find the new **webhookrelay** connector in the list and click **Connect**. A Webhook Relay sign-in / authorization window opens — log in and approve access to link the connector to your account (this is the OAuth step; no token needs to be entered manually).
5. In a chat, enable the **webhookrelay** connector from the tools/connectors menu, then try a prompt like:
  - "List all my webhook buckets"
  - "Create a new bucket that forwards to [https://example.com](https://example.com)"
  - "Which buckets had failed deliveries in the last 24 hours?"

![Claude.ai connection](https://webhookrelay.com/docs/mcp/images/docs/mcp/claude.png)

## [Use MCP from an Agent](#use-mcp-from-an-agent)

Once configured, your agent can call MCP tools to create and manage buckets, inspect webhook logs, and work with transform functions:

![Webhook Relay MCP usage from an agent](https://webhookrelay.com/docs/mcp/images/docs/mcp/agent_use.png)

## [Resource](#resource)

The MCP server exposes the following resource:

| URI | Description |
| --- | --- |
| `webhookrelay://docs/functions/javascript-api` | Complete API reference for writing JavaScript transform functions. Covers the request object (`r`), config (`cfg`), HTTP client, crypto, time, BigQuery, and Mailgun modules. |

## [Tools](#tools)

### [Bucket Management](#bucket-management)

| Tool | Description | Params |
| --- | --- | --- |
| `list_buckets` | List all webhook buckets for the account, including their inputs (public endpoints) and outputs (forwarding destinations). | None |
| `create_bucket` | Create a new bucket with a default public endpoint. Optionally create an output in the same call by providing a destination URL. Returns the public webhook URL. Attach transform functions at creation time via `input_function_id` / `output_function_id`. | **`name`**, `description`, `destination`, `internal`, `input_function_id`, `output_function_id` |
| `update_bucket` | Update a bucket's name or description. | **`id`**, `name`, `description` |
| `delete_bucket` | Delete a bucket and all its inputs/outputs (destructive). | **`id`** |

### [Inputs (public endpoints)](#inputs-public-endpoints)

`create_bucket` already creates one default input. Use these tools when a bucket needs more than one endpoint, or to fine-tune endpoint behaviour (custom response, custom domain, path prefix, TLS policy).

| Tool | Description | Params |
| --- | --- | --- |
| `get_input` | Get an input's full configuration: response settings, custom domain, path prefix and TLS settings. Read-only. | **`input_id`** |
| `create_input` | Create an additional public HTTPS endpoint in a bucket. All inputs in a bucket forward to the same outputs. | **`bucket_id`**, **`name`**, `description`, `function_id`, `response_status_code`, `response_body`, `response_headers`, `response_from_output`, `custom_domain`, `path_prefix`, `strip_path_prefix`, `tls_version`, `legacy_tls` |
| `update_input` | Update an input. Only provided fields change; pass an empty string to clear a text field (e.g. `function_id: ""` detaches the function). | **`input_id`**, `name`, `description`, `function_id`, `response_status_code`, `response_body`, `response_headers`, `response_from_output`, `custom_domain`, `path_prefix`, `strip_path_prefix`, `tls_version`, `legacy_tls` |
| `delete_input` | Delete an input. Its endpoint stops accepting webhooks immediately; logs are unaffected (destructive). | **`input_id`** |

### [Outputs (forwarding destinations)](#outputs-forwarding-destinations)

| Tool | Description | Params |
| --- | --- | --- |
| `get_output` | Get an output's full configuration: override headers, retry/timeout settings, filtering rules and durable retry config. Read-only. | **`output_id`** |
| `create_output` | Create a forwarding destination in a bucket. Every webhook received by the bucket's inputs is forwarded to each enabled output whose rules match. Use `internal=true` for private-network destinations reached via a relay agent. For cloud services (SQS, PubSub, …) use `create_service_connection_output` instead. | **`bucket_id`**, **`name`**, **`destination`**, `description`, `internal`, `function_id`, `headers`, `lock_path`, `disabled`, `retries`, `timeout_seconds`, `tls_verification`, `rules`, `durability` |
| `update_output` | Update an output. Only provided fields change; pass an empty string to clear a text field. Filtering rules are managed separately via `set_output_rules` / `clear_output_rules`. | **`output_id`**, `name`, `description`, `destination`, `internal`, `function_id`, `headers`, `lock_path`, `disabled`, `retries`, `timeout_seconds`, `tls_verification`, `durability` |
| `delete_output` | Delete an output. Webhooks are no longer forwarded to its destination (destructive). | **`output_id`** |
| `set_output_rules` | Set filtering rules so an output only forwards webhooks for which the rule tree evaluates to true. See [Output filtering rules](#output-filtering-rules) below for the rule-tree format. | **`output_id`**, **`rules`** |
| `clear_output_rules` | Remove all filtering rules so the output forwards every webhook again. | **`output_id`** |

### [Webhook Logs & Delivery Health](#webhook-logs-delivery-health)

| Tool | Description | Params |
| --- | --- | --- |
| `list_webhook_logs` | List webhook logs for a bucket in summary format (status code, status, method, timestamp, duration). Filter by delivery status (e.g. `status=failed`), output and a `from`/`to` time window. Read-only. | **`bucket_id`**, `output_id`, `status`, `from`, `to`, `limit` (default 20), `offset`, `cursor` |
| `get_webhook_log` | Get full details of a single log including request/response headers and body. Read-only. | **`id`**, **`bucket_id`** |
| `get_logs_stats` | Get delivery statistics (received / success / failures). By default returns one per-day series for the account (or one bucket via `bucket_id`). Pass `group_by=bucket` for a per-bucket leaderboard ranked by failures — the fastest way to find _which_ buckets are failing in one call. Read-only. | `bucket_id`, `group_by` (`bucket`), `from`, `to`, `limit` (default 10, max 100), `offset` |
| `retry_webhook` | Retry (resend) a webhook log through its bucket's delivery pipeline, or to a single output via `output_id`. `process_policy` controls whether rules and functions re-run (`skip` / `force`). | **`id`**, `bucket_id`, `output_id`, `process_policy` |

> **Note:** `status` accepts `sent`, `failed`, `stalled`, `received` or `rejected`. `from` / `to` accept `YYYY-MM-DD` or RFC3339. `list_webhook_logs` and `get_webhook_log` are always bucket-scoped and **require `bucket_id`**.

### [Transform Functions](#transform-functions)

| Tool | Description | Params |
| --- | --- | --- |
| `list_functions` | List all transform functions in the account. Read-only. | None |
| `get_function` | Get a function's full details including source code. Read-only. | **`id`** |
| `create_function` | Create a new transform function. Supported drivers: `lua`, `js`. | **`name`**, **`driver`**, **`code`** |
| `update_function` | Update an existing function's name, driver, or code. | **`id`**, `name`, `driver`, `code` |
| `execute` | Execute a transform function with a synthetic request payload. Use to test functions before attaching them. | **`function_id`**, `method`, `path`, `raw_query`, `headers`, `request_body` |

### [Function Attachments](#function-attachments)

| Tool | Description | Params |
| --- | --- | --- |
| `attach_function` | Attach a transform function to an input or output so it processes webhooks in transit. | **`resource_type`** (`input`/`output`), **`resource_id`**, **`function_id`** |
| `detach_function` | Detach a transform function from an input or output. | **`resource_type`** (`input`/`output`), **`resource_id`** |

### [Service Connections](#service-connections)

| Tool | Description | Params |
| --- | --- | --- |
| `list_service_connections` | List all service connections (GCP, AWS, Azure) for the account. Read-only. | None |
| `get_service_connection` | Get a service connection's details (secrets redacted). Read-only. | **`id`** |
| `create_service_connection` | Create a connection to a cloud provider. GCP: `gcp_project_id` + `gcp_service_account_key`. AWS: `aws_access_key_id` + `aws_secret_access_key`. Azure: `azure_client_id` + `azure_client_secret` + `azure_tenant_id`. | **`name`**, **`service_type`** (`gcp`/`aws`/`azure`), provider credentials |
| `update_service_connection` | Update a connection's name or credentials. Only non-empty fields are updated. | **`id`**, `name`, provider credentials |
| `delete_service_connection` | Delete a service connection (destructive). | **`id`** |

### [Service Connection Inputs](#service-connection-inputs)

| Tool | Description | Params |
| --- | --- | --- |
| `list_service_connection_inputs` | List cloud event subscription inputs for a bucket. Read-only. | **`bucket_id`** |
| `create_service_connection_input` | Subscribe to cloud events and forward them into a bucket. Per `input_type`: `gcp_pubsub` → `gcp_pubsub_subscription_name`; `gcp_gcs` → `gcp_gcs_bucket_name`; `aws_s3` → `aws_s3_bucket_name` + `aws_s3_region`; `aws_sqs` → `aws_sqs_queue_url`; `aws_sns` → `aws_sns_topic_arn`. | **`bucket_id`**, **`service_connection_id`**, **`input_type`**, `name`, `function_id`, type-specific fields |
| `delete_service_connection_input` | Delete a service connection input from a bucket (destructive). | **`bucket_id`**, **`input_id`** |

### [Service Connection Outputs](#service-connection-outputs)

| Tool | Description | Params |
| --- | --- | --- |
| `list_service_connection_outputs` | List cloud service outputs for a bucket. Read-only. | **`bucket_id`** |
| `create_service_connection_output` | Forward webhooks from a bucket to cloud services. Per `output_type`: `gcp_pubsub` → `gcp_pubsub_topic_name`; `gcp_gcs` → `gcp_gcs_bucket_name`; `aws_s3` → `aws_s3_bucket_name` + `aws_s3_region`; `aws_sqs` → `aws_sqs_queue_url`; `aws_sns` → `aws_sns_topic_arn`. | **`bucket_id`**, **`service_connection_id`**, **`output_type`**, `name`, `function_id`, type-specific fields |
| `delete_service_connection_output` | Delete a service connection output from a bucket (destructive). | **`bucket_id`**, **`output_id`** |

## [Investigating delivery failures](#investigating-delivery-failures)

The delivery-health tools are designed to localise failures fast, without looping a stats call per bucket:

1. **Find which buckets are failing** — call `get_logs_stats` with `group_by=bucket` for an account-wide leaderboard ranked by failure count (paged via `limit`/`offset`).
2. **Drill into a bucket's trend** — call `get_logs_stats` with `bucket_id` for its per-day received/success/failure series.
3. **Find the broken webhooks** — call `list_webhook_logs` with `bucket_id` and `status=failed` (optionally `from`/`to`/`output_id`).
4. **Inspect one** — call `get_webhook_log` with the log `id` and its `bucket_id` for full request/response detail.
5. **Re-deliver** — call `retry_webhook` with the log `id` (optionally a single `output_id`, and `process_policy` `skip`/`force`).

## [Output filtering rules](#output-filtering-rules)

`set_output_rules` takes a rule tree with exactly one top-level key:

- `match` — a single condition
- `and` / `or` — arrays of nested rule trees
- `not` — negates a nested tree

A `match` condition has a `type` and operands. Common types: `value` (exact match, uses `value`), `contains` / `does-not-contain` (uses `substring`), `regex` (uses `regex`), `payload-hash-sha1` / `payload-hash-sha256` (HMAC signature verification, uses `secret`), and `ip-whitelist` (uses `ip-range` CIDR). The `parameter.source` is one of `payload` (JSON body field, dot notation for nesting), `header`, `query`, `path`, `string`, `entire-payload`, `entire-query` or `entire-headers`.

Example — only forward GitHub `push` events on the `main` branch:

```
{
  "and": [
    { "match": { "type": "value", "value": "refs/heads/main", "parameter": { "source": "payload", "name": "ref" } } },
    { "match": { "type": "value", "value": "push", "parameter": { "source": "header", "name": "X-GitHub-Event" } } }
  ]
}
```

## [Key Concepts](#key-concepts)

- **Bucket**: A logical container grouping one or more inputs with one or more outputs.
- **Input**: A public HTTPS endpoint (URL) that receives webhooks from third parties. A bucket can have several inputs (each with its own URL, custom domain, response and TLS settings); they all feed the same outputs.
- **Output**: A destination URL where received webhooks are forwarded. Set `internal=true` for private-network/localhost destinations (requires a connected relay agent). Outputs support override headers, retries/timeouts, filtering rules and durable long-period retries.
- **Function**: A Lua or JavaScript snippet that transforms webhooks in transit. Functions are attached to inputs (runs before routing) or outputs (runs before forwarding).
- **Service Connection**: Credentials for a cloud provider (GCP, AWS, Azure) that enable cloud event subscriptions (inputs) and cloud service forwarding (outputs).

## [Important Behavior for JavaScript Functions](#important-behavior-for-javascript-functions)

Before creating or updating JavaScript transform functions, agents must first read:

- `webhookrelay://docs/functions/javascript-api`

JavaScript transforms run in a custom runtime. They must mutate the global `r` object directly, and standard Node.js/browser APIs are not available.

Did this page help you?