# Deck of Cards MCP > Deck of Cards starts your simulation instantly. This MCP lets you build, run, and manage complex card games—from basic poker hands to full Monte Carlo probability experiments—all through natural conversation with your AI agent. You control the entire game state: shuffle decks, draw specific cards, organize piles, and track remaining counts without writing a single line of setup code. ## Overview - **Category:** productivity - **Price:** Free - **Tags:** playing-cards, game-mechanics, simulation, api-integration, randomization ## Description Running card simulations used to mean complex backend logic or tedious manual randomization. Now, you can build playable games directly within your workflow using this MCP. Your AI agent acts as the dealer and game engine, managing every single state change for you. You tell it what to do—like 'deal a hand of five cards'—and it handles everything from creating the deck to tracking which cards are left in the main stack. This capability is crucial for anything involving probability or pure chance. Since Vinkius hosts this MCP, connecting it to your agent means you get immediate access to advanced game logic that was once restricted to specialized applications, letting you focus purely on the outcome of the simulation. ## Tools ### add_to_pile Adds specified cards to a named pile when instructed by your agent. ### create_new_deck Initializes a brand new, fully shuffled deck of standard playing cards. ### create_partial_deck Builds a custom deck containing only the specific card types you name (e.g., all Aces and Kings). ### draw_cards Removes cards from the top of the main deck and places them in your designated hand or pile. ### draw_from_pile_bottom Retrieves a card specifically from the bottom of a designated pile. ### draw_from_pile_random Selects and removes any random card found within a specific named pile. ### draw_from_pile Pulls a card from the center of an existing named pile, rather than the top. ### list_pile Displays every single card currently held or stored in a specified named pile. ### reshuffle_deck Mixes an existing deck of cards to randomize the entire sequence of play. ### return_pile_to_deck Moves all cards from a named pile back into the primary, active card deck. ### return_to_deck Sends specified individual cards or a small group of cards back to the main playing deck. ### shuffle_new_deck Creates and shuffles a brand new deck, with an option to use multiple decks for advanced simulations. ### shuffle_pile Randomizes the order of cards only within one specific named pile. ## Prompt Examples **Prompt:** ``` Create a new shuffled deck using 6 standard decks for a blackjack simulation. ``` **Response:** ``` I've initialized a new multi-deck set. Deck ID: `3p40paa87x90`. It contains 312 cards and is fully shuffled. Ready to deal! ``` **Prompt:** ``` Draw 5 cards from deck 3p40paa87x90 and add them to a pile named 'player_hand'. ``` **Response:** ``` I've drawn 5 cards (8H, AD, 2C, KS, 4D) and moved them to the 'player_hand' pile. There are 307 cards remaining in the main deck. ``` **Prompt:** ``` List all the cards currently in the 'discard' pile for deck 3p40paa87x90. ``` **Response:** ``` The 'discard' pile currently contains 3 cards: Queen of Hearts (QH), 10 of Spades (0S), and 5 of Diamonds (5D). ``` ## Capabilities ### Manage decks and piles Instantly set up complex game environments by creating new standard or partial card decks, and organizing multiple named piles for players and discards. ### Execute precise draws Tell the AI exactly how to draw cards—from the top, bottom, random spot, or a specific player's hand. ### Control card flow Move cards between piles and decks using functions like returning used cards back into the main deck for reuse. ### Track game state Get an accurate list of all cards in any named pile or know exactly how many cards are left in the primary deck. ## Use Cases ### Simulating Blackjack payouts A developer asks their agent to set up six standard decks using `shuffle_new_deck`. The agent initializes the environment. Then, it draws 5 cards and adds them to a 'player hand' pile. Finally, it uses `list_pile` to confirm the exact five cards drawn for payout calculation. ### Teaching probability of suits An educator asks the agent to create a partial deck containing only Hearts and Spades using `create_partial_deck`. They then instruct the agent to draw 10 random cards using `draw_cards` so the student can calculate the ratio manually. ### Modeling multi-player card games A game designer needs three distinct player hands. The agent first creates these named piles, then uses `add_to_pile` repeatedly to simulate dealing cards one by one, maintaining perfect state tracking across all three locations. ### Testing card recycling mechanics The simulation ends with a 'discard' pile. To run the next round, the agent uses `return_pile_to_deck` to move all discards back into the main deck before running another draw sequence. ## Benefits - Stop writing boilerplate state management code. You can initialize the entire environment, whether you need a single deck or multiple decks for complex casino simulations, using `create_new_deck` or `shuffle_new_deck`. - The agent handles all draw mechanics, so you never manually track inventory. Need five cards? Simply ask your agent to use `draw_cards`, and it accounts for the reduction in the main deck count immediately. - You gain granular control over card movement. Instead of just drawing from the top, tools like `draw_from_pile` or `draw_from_pile_bottom` let you simulate specific gameplay rules (e.g., a 'skip' draw). - Keep track of everything without juggling multiple spreadsheets. If players discard cards into named piles, use `list_pile` to see exactly what they left behind. - Need to adjust the game flow? Use `return_to_deck` or `return_pile_to_deck` to send used cards back into play, keeping the simulation accurate for continuous gameplay. ## How It Works The bottom line is you use natural conversation to control sophisticated game mechanics that would otherwise require a dedicated backend application. 1. First, initialize your session by telling your agent to create a new deck, or provide an existing Deck ID for continuity. 2. Next, give specific commands—for instance, 'Draw 5 cards and put them in the player hand'—and let your agent execute the necessary draws and pile movements. 3. Finally, review the results; the system reports the card draw details and the updated count of cards remaining in the main deck. ## Frequently Asked Questions **How do I start a multi-deck simulation using shuffle_new_deck?** Use `shuffle_new_deck` and specify the number of decks required, like six. The agent will initialize all those decks, give you a total card count, and ready the environment for your first round. **Can I simulate drawing only specific cards? (create_partial_deck)** Yes. Use `create_partial_deck` to generate a deck containing just what you need—say, all Queens and Jacks—and then proceed with normal draw mechanics on that custom set. **What's the difference between return_to_deck and return_pile_to_deck?** Use `return_to_deck` when sending a small, specific selection of cards back to play. Use `return_pile_to_deck` when you need to send every single card from an entire named pile. **How do I check what's in the discard pile? (list_pile)** You call `list_pile` and specify 'discard'. The agent will immediately list out every card name and value currently stored in that named location. **Does draw_cards affect the main deck count?** Yes, absolutely. Every time you use `draw_cards`, the MCP tracks it and updates the remaining count of cards in the primary deck for accurate state management. **What’s the difference between running `reshuffle_deck` and using `shuffle_pile`?** `Reshuffle_deck` mixes all cards in the main deck, resetting their order. Conversely, `shuffle_pile` only randomizes the card sequence within a specific pile you name. **What happens if I try to use `draw_from_pile` when the target pile is empty?** The system handles this gracefully. Instead of returning an error, it reports that the specified pile has no cards remaining for drawing, stopping the process immediately. **How does using `add_to_pile` affect the main deck count or state?** It doesn't change the main deck count. You manually place cards into a named pile, bypassing the natural draw mechanics entirely and keeping them out of the active deck. **Can I create a deck that includes Jokers for games like Rummy?** Yes! Use the `create_new_deck` tool and set the `jokers_enabled` parameter to true. This will add two Jokers to your standard 52-card deck. **Is it possible to draw cards from the bottom of a pile instead of the top?** Absolutely. Use the `draw_from_pile_bottom` tool by specifying the `deck_id` and `pile_name`. You can also use `draw_from_pile_random` if you need a random card from the middle of a pile. **How do I simulate a casino game that uses 6 shuffled decks?** Use the `shuffle_new_deck` tool and set the `deck_count` parameter to 6. This will return a single `deck_id` containing 312 cards (52 * 6) in a randomized order.