MCP Quickstart

Use Payloadr MCP when your AI agent needs to send webhooks and verify they actually arrived.

What you need

• A Payloadr account
• A Payloadr API key from /dashboard/api-keys
• An MCP-compatible client (Claude Desktop, Cursor, etc.)
• Your Payloadr MCP connection details:
  • MCP URL: https://mcp.payloadr.dev/mcp
  • Your Payloadr API key for MCP auth

Connect your MCP client

Add a remote MCP server in your client with:

• URL: https://mcp.payloadr.dev/mcp
• Header: Authorization: Bearer <PAYLOADR_API_KEY>

Use the same API key you generate in Payloadr Dashboard.

MCP configuration examples

Replace pk_live_xxx with your own Payloadr API key.

Claude

{
  "mcpServers": {
    "payloadr": {
      "type": "streamable-http",
      "url": "https://mcp.payloadr.dev/mcp",
      "headers": {
        "Authorization": "Bearer pk_live_xxx"
      }
    }
  }
}

OpenCode

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "payloadr": {
      "type": "remote",
      "url": "https://mcp.payloadr.dev/mcp",
      "oauth": false,
      "headers": {
        "Authorization": "Bearer {env:PAYLOADR_API_KEY}"
      }
    }
  }
}

oauth: false is required for Payloadr MCP in OpenCode. Without it, OpenCode tries OAuth discovery and fails with errors like Cannot POST /register.

Codex

{
  "mcpServers": {
    "payloadr": {
      "type": "streamable-http",
      "url": "https://mcp.payloadr.dev/mcp",
      "headers": {
        "Authorization": "Bearer pk_live_xxx"
      }
    }
  }
}

How tool auth works

The MCP server authenticates you from the bearer header and runs tools in your own Payloadr workspace.

Core tools

• create_endpoint create a webhook endpoint
• list_events list recent webhook events for an endpoint
• get_event fetch one event with full payload and headers
• wait_for_event wait for a new incoming webhook
• replay_event replay a captured event to another target URL
• assert_event assert expected fields on an event

Typical workflow

1. Call create_endpoint for a test flow.
2. Trigger your integration to send a webhook to that endpoint.
3. Call wait_for_event to block until the webhook arrives.
4. Inspect with get_event.
5. Validate with assert_event.
6. If needed, use replay_event against your local or staging target.

Example prompts

• "Create a Payloadr endpoint for Stripe test events."
• "Wait up to 60 seconds for a new checkout.session.completed event."
• "Assert that body.type equals checkout.session.completed."
• "Replay this event to my staging webhook URL."

Security best practices

• Keep your Payloadr API key secret.
• Use test keys in non-production workflows.
• Rotate keys if they are shared or leaked.