How to Use the Deck of Cards MCP in Pydantic AI

Q: Can I build a Solitaire agent with Pydantic AI and the Deck of Cards server?

Yes, this is a great use case. Your agent would use shufflenewdeck to start, then drawcards and the various ...pile tools to manage the tableau and foundation piles, with Pydantic AI ensuring every move is based on valid data.

Q: What's the setup for Deck of Cards with Pydantic AI?

After pip install "pydantic-ai-slimmcp", you create an MCPToolset with your Vinkius server URL. Then you just pass that toolset into your Agent constructor. It's straightforward.

Q: What's the difference between reshuffledeck and shufflenewdeck?

Use shufflenewdeck at the very beginning of a game to get a brand new, shuffled deck. Use reshuffledeck during a game to re-randomize the cards that are currently in the deck, not including cards in piles or hands.

Add type-safe card game mechanics to your agent. Pydantic AI validates every response from the Deck of Cards 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 Deck of Cards MCP to Pydantic AI

Create your Vinkius account to connect Deck of Cards 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 Deck of Cards with Pydantic AI

Ask AI about this MCP

ChatGPT

Claude

Perplexity

Create Decks with Guaranteed Correctness

Start your game or simulation with confidence. The `create_new_deck` tool gives you a standard 52-card deck, while `create_partial_deck` lets you build a custom one. You can also get a shuffled deck immediately with `shuffle_new_deck`. Here’s the key: Pydantic AI validates the server's response against a Pydantic model. If this MCP server returns a malformed deck ID or an incorrect card count, your code will raise a `ValidationError` instantly. No silent failures, no bad data corrupting your agent's state.

Manipulate Cards with Type-Safe Tools

This MCP server gives your agent a full set of actions for managing a card game. It can `draw_cards` from the deck or use a whole suite of pile tools: `add_to_pile`, `list_pile`, `draw_from_pile`, and even `shuffle_pile`. Every time your agent calls one of these tools, Pydantic AI checks the output. When you draw cards, it ensures the response is a list of valid card objects. This runtime validation means you can trust the state of your game without writing tons of defensive code.

Reset and Reshuffle with Pydantic AI

Keep your game logic clean and predictable. Use `reshuffle_deck` to randomize an existing deck, or `return_to_deck` to put cards back. These tools are essential for managing rounds in a game. Because Pydantic AI is model-agnostic, you can use these verified tools with any LLM you prefer—OpenAI, Anthropic, or a local model. The framework provides the safety layer, and this server provides the reliable game-state functions for your agent to call.

Setup guide

Set up Deck of Cards 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": {
        "deck-of-cards-mcp": {
            "url": "https://edge.vinkius.com/[YOUR_TOKEN_HERE]/mcp"
        }
    }
})

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

result = await agent.run("List recent Deck of Cards 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 Deck of Cards API. 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 Deck of Cards 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 Deck of Cards MCP in Pydantic AI

Pydantic AI automatically creates models based on the MCP server's schema. When your agent calls `draw_cards`, the framework validates the JSON response to ensure it matches the expected structure. If not, it fails loudly.

Yes, this is a great use case. Your agent would use `shuffle_new_deck` to start, then `draw_cards` and the various `..._pile` tools to manage the tableau and foundation piles, with Pydantic AI ensuring every move is based on valid data.

After `pip install "pydantic-ai-slim[mcp]"`, you create an `MCPToolset` with your Vinkius server URL. Then you just pass that toolset into your `Agent` constructor. It's straightforward.

Use `shuffle_new_deck` at the very beginning of a game to get a brand new, shuffled deck. Use `reshuffle_deck` during a game to re-randomize the cards that are currently in the deck, not including cards in piles or hands.

No. The server only receives requests to manipulate card data like deck IDs and card codes. Your agent's internal logic and Pydantic models never leave your environment. Vinkius secures the connection with a single token and runs the server in a sandboxed instance for each request.

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