How to Use the Gift Up! MCP in Pydantic AI

Q: How do I register the Gift Up! MCP Server with Pydantic AI?

You use the MCPToolset class initialized with your Vinkius HTTP endpoint. This registers all 12 Gift Up! tools with your Pydantic AI agent, exposing them as fully typed functions.

Q: How does the agent verify connection state?

Your agent can call verifyapiconnection during startup to ensure the API is reachable. This prevents Pydantic AI from running complex reasoning loops when the backend is offline.

Run type-safe Gift Up! order tracking and card redemptions with strict Pydantic AI runtime validation.

See Vinkius in Action

Works with every AI agent you already use

…and any MCP-compatible client

MCP Servers - Free for Subscribers

Connect Gift Up! MCP to Pydantic AI

Create your Vinkius account to connect Gift Up! 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 Gift Up! with Pydantic AI

Ask AI about this MCP

ChatGPT

Claude

Perplexity

Type-safe gift card balance validation

The `validate_gift_card` tool checks the exact balance and validity of a gift card while enforcing strict Pydantic AI schemas on the response. This ensures your python code receives guaranteed data types, preventing runtime crashes from unexpected API payloads. This MCP Server setup guarantees that your agent never acts on corrupted or malformed balance data when calling `get_card_details` to retrieve history.

Strict schema validation for card redemptions

The `redeem_gift_card` tool executes partial card redemptions with strict runtime type checks on the deduction amount. Using Pydantic AI, your agent validates that the requested charge is a valid positive float before sending the API request. This MCP Server tool handles the full sweep under the same type-safe constraints when calling `redeem_gift_card_full`. This prevents accidental double-spending or negative balance errors in your e-commerce pipeline.

Structured metadata and order queries

The `update_order_metadata` tool modifies custom fields on an order while validating the payload against your defined Pydantic models. This ensures your support agents only write structured, clean tracking notes back to the Gift Up! database. When searching for historical data, `find_order_by_ref` and `get_order_details` return strictly typed objects. Your Pydantic AI system can confidently parse these records to resolve customer disputes without silent failures.

Setup guide

Set up Gift Up! 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": {
        "gift-up-mcp": {
            "url": "https://edge.vinkius.com/[YOUR_TOKEN_HERE]/mcp"
        }
    }
})

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

result = await agent.run("List recent Gift Up! 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 Gift Up!. 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 Gift Up! 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 Gift Up! MCP in Pydantic AI

You use the `MCPToolset` class initialized with your Vinkius HTTP endpoint. This registers all 12 Gift Up! tools with your Pydantic AI agent, exposing them as fully typed functions.

The system will raise a validation error immediately instead of passing bad data to the model. This ensures your Pydantic AI agent fails loudly and safely before executing critical financial tools like `redeem_gift_card`.

Yes, because Pydantic AI is model-agnostic, you can use these tools with any supported model. Your local or commercial model will call `get_card_details` using the exact same JSON schema.

Your agent can call `verify_api_connection` during startup to ensure the API is reachable. This prevents Pydantic AI from running complex reasoning loops when the backend is offline.

All raw API transactions, card codes, and order records are proxied through Vinkius's ephemeral sandboxes. Pydantic AI only interacts with the validated outputs, keeping your master merchant keys hidden from the agent's runtime 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