How to Use the Hookdeck MCP in Pydantic AI

Q: How do I connect Pydantic AI to the Hookdeck MCP Server?

Install pydantic-ai-slimmcp. Initialize the MCPToolset with your Vinkius HTTP endpoint, and pass it to your Agent's toolsets parameter. Avoid using the deprecated MCPServerHTTP class.

Q: Can Pydantic AI manage Hookdeck retries automatically?

Yes. You can build an agent that monitors listattempts and executes retryevent based on specific failure codes, all while enforcing type safety on the retry parameters.

Q: How does the MCP integration handle sensitive webhook payloads?

Calling getevent exposes the raw JSON payload and HTTP headers of your incoming webhooks. The Vinkius architecture isolates this interaction inside a V8 sandbox, ensuring your authentication tokens remain strictly separated from the execution environment.

Type-safe webhook management for Pydantic AI agents using the Hookdeck 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 Pydantic AI

Create your Vinkius account to connect Hookdeck to Pydantic AI 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 Pydantic AI

Ask AI about this MCP

ChatGPT

Claude

Perplexity

Type-Safe Event Inspection

Pydantic AI enforces strict schema validation on every response from `get_event` and `list_requests`. If the API returns unexpected fields or missing data, your agent fails loudly with a validation error. You never have to worry about silent data corruption. This strictness is critical for production infrastructure. When the agent pulls delivery statistics via `get_metrics_attempts`, the SDK guarantees the resulting integer matches your defined Pydantic models before executing any retry logic.

Deterministic Routing Control

Your agent provisions new webhooks by calling `create_source` and `create_destination` through the MCP tools. Because Pydantic AI is model-agnostic, you can swap between Claude or Gemini without rewriting your webhook management logic. The agent maps the exact parameters required for `create_connection`. Configuration drift stops here. The agent audits your existing setup with `list_connections` and compares it against your expected state, fixing discrepancies automatically via `update_connection`.

Validated Payload Mutations

The agent drafts JavaScript logic for incoming webhooks and evaluates it using `test_transformation`. Pydantic AI parses the execution results to confirm the output schema matches your downstream API requirements. If the test passes, the agent deploys the code using `create_transformation`. If it fails, the strict validation catches the error immediately, forcing the agent to rewrite the logic instead of deploying broken code to production.

Setup guide

Set up Hookdeck MCP in Pydantic AI

Prerequisites

Python 3.10+ installed
pydantic-ai-slim[fastmcp] package
Active Vinkius subscription with a valid endpoint token

1

Install Pydantic AI with FastMCP
Run pip install "pydantic-ai-slim[fastmcp]". The FastMCP toolset replaces the deprecated MCPServerHTTP class with full protocol support.
2

Configure the FastMCPToolset
Pass a JSON-style config dict to FastMCPToolset with your Vinkius URL. Replace [YOUR_TOKEN_HERE] with your token from cloud.vinkius.com. Supports Streamable HTTP, SSE, and Stdio transports.
3

Create and run your agent
Pass the toolset to Agent(toolsets=[toolset]) and call agent.run(). Swap openai:gpt-4o for any supported model — Anthropic, Google, Mistral, or Groq.

agent.py

from pydantic_ai import Agent
from pydantic_ai.toolsets.fastmcp import FastMCPToolset

toolset = FastMCPToolset({
    "mcpServers": {
        "hookdeck-mcp": {
            "url": "https://edge.vinkius.com/[YOUR_TOKEN_HERE]/mcp"
        }
    }
})

agent = Agent(
    "openai:gpt-4o",
    toolsets=[toolset],
    system_prompt="You have access to Hookdeck tools.",
)

result = await agent.run("List recent Hookdeck transactions")
print(result.output)

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 Pydantic AI

Install `pydantic-ai-slim[mcp]`. Initialize the `MCPToolset` with your Vinkius HTTP endpoint, and pass it to your Agent's `toolsets` parameter. Avoid using the deprecated `MCPServerHTTP` class.

Pydantic AI validates every tool response at runtime. When you call `get_issue_trigger`, the framework guarantees the returned JSON strictly matches your predefined data models.

Yes. You can build an agent that monitors `list_attempts` and executes `retry_event` based on specific failure codes, all while enforcing type safety on the retry parameters.

The framework is completely model-agnostic. You can route webhooks using local models, provided they support tool calling capabilities.

Calling `get_event` exposes the raw JSON payload and HTTP headers of your incoming webhooks. The Vinkius architecture isolates this interaction inside a V8 sandbox, ensuring your authentication tokens remain strictly separated from the execution environment.

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