How to Use the Hookdeck MCP in OpenAI Agents SDK

Q: How do I configure the Hookdeck MCP Server in the OpenAI Agents SDK?

Install openai-agents via pip. Initialize MCPServerStreamableHttp with your Vinkius endpoint URL and pass it to the Agent constructor in the mcpservers list. Set cacheToolsList=True to speed up tool discovery.

Q: Can my OpenAI Agents SDK deployment automatically retry failed Hookdeck webhooks?

Yes. Your agent can monitor failed deliveries via listattempts and trigger retryevent programmatically. You define the logic for when and how aggressively it retries.

Q: What happens if an agent tries to delete a Hookdeck production connection?

The OpenAI Agents SDK guardrails intercept the deleteconnection call before execution. You can enforce human-in-the-loop approval for destructive actions while allowing read-only metrics gathering.

Q: How does the agent test payload transformations?

It calls testtransformation with a sample payload and the proposed JavaScript code. The server returns the execution result, letting the agent iterate on the script until it passes.

Q: Does the Hookdeck MCP integration expose our raw webhook payloads to OpenAI?

Only if your agent explicitly requests them. Tools like getevent and listevents fetch the raw JSON payloads, which are then processed in your isolated V8 sandbox. Vinkius maintains zero-trust ephemeral sessions, ensuring no persistent storage of your incoming HTTP request data.

Build production-ready webhook routing agents using the OpenAI Agents SDK and this MCP Server.

See Vinkius in Action

Works with every AI agent you already use

…and any MCP-compatible client

MCP Servers - Free for Subscribers

Connect Hookdeck MCP to OpenAI Agents SDK

Create your Vinkius account to connect Hookdeck to OpenAI Agents SDK and route execution through our secure gateway. The platform manages server hosting, runtime updates, and security layers. Configuration requires no manual server provisioning.

GDPR Free for Subscribers

Setup Hookdeck with OpenAI Agents SDK

Ask AI about this MCP

ChatGPT

Claude

Perplexity

Dynamic Webhook Routing with OpenAI Agents SDK

Your OpenAI agent manages event routing directly by calling `create_connection` and `update_connection` through the MCP integration. Built-in SDK guardrails validate these configuration changes before they hit production. You can configure multiple sources and destinations without leaving the Python context. Handoffs between specialized agents change how you handle incidents. One agent analyzes incoming traffic patterns using `get_metrics_requests`, while another pauses failing endpoints with `pause_connection`. Tracing via the OpenAI dashboard tracks exactly when and why an agent modified your routing rules.

Code-Driven Payload Transformations

Hookdeck exposes `create_transformation` to let your agent write and deploy JavaScript payload modifiers. Testing happens immediately via `test_transformation` to ensure the code works against actual webhook data. If the output fails your safety constraints, the agent catches it before deployment. Maintaining these scripts usually requires manual developer intervention. Now, your agent pulls existing logic with `get_transformation`, refactors it based on new API requirements, and pushes the update with `update_transformation`.

Automated Incident Response

When a destination goes down, your agent detects the spike in failed deliveries using `get_metrics_attempts`. It then automatically pauses the connection using `pause_connection` to prevent queue exhaustion. Recovery is entirely programmatic. Once the endpoint stabilizes, the agent resumes traffic via `unpause_connection` and replays the backlog using `retry_event` or `retry_request`. You get full visibility into the recovery process through the SDK's native tracing tools.

Setup guide

Set up Hookdeck MCP in OpenAI Agents SDK

Prerequisites

Python 3.10+ installed
openai-agents package (pip install openai-agents)
Active Vinkius subscription with a valid endpoint token

1

Install the SDK

Run pip install openai-agents to install the OpenAI Agents SDK. The MCP integration is built-in — no extra dependencies needed.
2

Connect via SSE transport

Use MCPServerSse with your Vinkius endpoint URL. Replace [YOUR_TOKEN_HERE] with your token from cloud.vinkius.com. The SDK auto-discovers all Hookdeck tools at runtime.
3

Create your Agent

Pass the MCP to Agent(mcp_servers=[server]). The agent receives Hookdeck tools as native definitions — JSON schemas resolve automatically.
4

Run the agent

Call Runner.run(agent, prompt) to execute. The agent invokes the appropriate Hookdeck tools and returns structured results. Copy the full example on the right to get started.

agent.py

import asyncio
from agents import Agent, Runner
from agents.mcp import MCPServerSse

async def main():
    async with MCPServerSse(
        url="https://edge.vinkius.com/[YOUR_TOKEN_HERE]/mcp"
    ) as server:
        agent = Agent(
            name="Hookdeck Agent",
            instructions="You have access to Hookdeck tools.",
            mcp_servers=[server],
        )
        result = await Runner.run(agent, "List recent transactions")
        print(result.final_output)

asyncio.run(main())

Get your connection token →

Independent Platform Disclaimer: Vinkius is an independent platform and is not affiliated with, endorsed by, sponsored by, verified by, or otherwise authorized by Hookdeck. All third-party trademarks, logos, and brand names are the property of their respective owners. Their use on this website is strictly for informational purposes to identify service compatibility and interoperability.

Why Choose Vinkius

Vinkius connects your tools to AI with real-time monitoring and automatic cost savings — all from one dashboard.

Connect Hookdeck now

Real-time monitoring

Live

visibility into every interaction

Connect your favorite tools to your AI and see exactly what's happening — every request, every response, in real time.

Built-in savings

60%

lower AI costs

Vinkius compresses data between your apps and your AI automatically. Lower bills every month — no configuration required.

Single dashboard

One

place for every integration

Every tool your AI connects to, managed from a single screen. One account, complete control.

Common questions about Hookdeck MCP in OpenAI Agents SDK

Install `openai-agents` via pip. Initialize `MCPServerStreamableHttp` with your Vinkius endpoint URL and pass it to the Agent constructor in the `mcp_servers` list. Set `cacheToolsList=True` to speed up tool discovery.

Yes. Your agent can monitor failed deliveries via `list_attempts` and trigger `retry_event` programmatically. You define the logic for when and how aggressively it retries.

The OpenAI Agents SDK guardrails intercept the `delete_connection` call before execution. You can enforce human-in-the-loop approval for destructive actions while allowing read-only metrics gathering.

It calls `test_transformation` with a sample payload and the proposed JavaScript code. The server returns the execution result, letting the agent iterate on the script until it passes.

Only if your agent explicitly requests them. Tools like `get_event` and `list_events` fetch the raw JSON payloads, which are then processed in your isolated V8 sandbox. Vinkius maintains zero-trust ephemeral sessions, ensuring no persistent storage of your incoming HTTP request data.

Use it with your favorite AI tools

Connect this server to Cursor, Claude, VS Code, and more.

OpenAI Agents SDK sdk-python

Google ADK sdk-python

Pydantic AI sdk-python

Vercel AI SDK sdk-typescript