# RandomDuck MCP > RandomDuck connects your AI agent to a library of duck images and GIFs for web development use. It lets you generate random ducks, get specific visuals by file number, or—most useful—visualize HTTP status codes (like 404 or 500) using `get_http_duck`. Use it when you need fun visuals or simple debugging aids in your chat client. ## Overview - **Category:** developer-tools - **Price:** Free - **Tags:** random-images, http-status, ducks, fun, visuals ## Description This server connects your AI agent to duck visuals—and it's way more useful than just sending random jokes. You use this when you need a quick, visual placeholder or when you gotta debug an HTTP status code in your chat client. It’s built for developers who don't wanna write boilerplate text. For visualizing technical errors, you call **`get_http_duck`**. This tool grabs a duck image or GIF that represents a specific HTTP status code; think 404 Not Found, 500 Server Error, or a clean 200 OK. You can show your teammates exactly what went wrong without having to type out long error messages. When you just need some quick visual filler—maybe for an early prototype that doesn't have real images yet—you use the random tools. To grab any completely random duck image or GIF, you run **`get_random_duck`**; remember, **`get_quack`** works the same way and fetches a totally unpredictable asset. If you only need the link and don’t want the whole chunk of content body, you use **`get_random_img_url`**. That gives you a direct, usable URL for any random duck image, which is perfect if you're just dropping it into an HTML snippet fast. If you know exactly what asset you need by its unique file number or identifier, you skip the randomness and go straight to **`get_specific_duck`**. This tool retrieves that single, exact duck asset for you. Need to check the whole stash before you pick? You run **`list_ducks`**, which gives a complete list of every filename and what kind of assets—images or GIFs—are currently in the collection. And if your team has an amazing custom image set they wanna use, they can contribute by using **`upload_duck`**. This submits their duck image file for review so it can get added to the server's asset pool. It’s simple: you call a tool, and it gives you back a specific visual aid—whether that’s an error code, a random placeholder, or a precise piece of art. ## Tools ### get_http_duck Gets a duck image or GIF that represents a specific HTTP status code, such as 404 or 200. This is used for technical visualization. ### list_ducks Returns a list of all available filenames and types of ducks currently in the collection for reference. ### get_quack Retrieves a completely random duck image or GIF (this tool acts as an alias for `get_random_duck`). ### get_random_img_url Provides a direct, usable URL for a random duck image without needing the full content body. ### get_random_duck Fetches any randomly selected duck image or GIF asset. ### get_specific_duck Retrieves a single duck asset when you know its specific file number or identifier. ### upload_duck Allows you to submit your own duck image file for review and potential inclusion in the server's asset pool. ## Prompt Examples **Prompt:** ``` Get a random duck image for me. ``` **Response:** ``` Quack! Here is a random duck for you: https://random-d.uk/api/32.jpg. Hope it makes your day better! ``` **Prompt:** ``` Show me the duck for HTTP 404 Not Found. ``` **Response:** ``` I've found the 404 duck! You can view it here: https://random-d.uk/api/http/404.jpg. It looks a bit lost, just like a 404 error. ``` **Prompt:** ``` List all available duck filenames. ``` **Response:** ``` I've retrieved the list. There are over 200 JPGs and 50 GIFs available, including special HTTP ducks for codes like 200, 403, and 500. Which one would you like to see? ``` ## Capabilities ### Visualize HTTP Status Codes The agent uses the `get_http_duck` tool to fetch a duck graphic that visually represents an HTTP status code (like 404 or 500). ### Generate Random Visual Placeholders Call `get_random_img_url` to immediately get the direct URL for any random duck image, perfect for quick prototypes. ### List Available Assets Run `list_ducks` to see every filename and asset type currently available in the entire collection. This is key for knowing what you can request by number. ### Fetch Specific Ducks Use `get_specific_duck` when you know the exact duck number or identifier you need to reference an asset. ## Use Cases ### Explaining a broken API endpoint A user knows the backend returned an HTTP 403 Forbidden error. Instead of pasting the cryptic code, they ask their agent to run `get_http_duck`. The agent responds with the 403 duck and a caption: 'Looks like we need permissions.' This is fast, visual, and avoids technical jargon. ### Building a quick UI mockup A front-end dev needs to show a component that fails on load. They use `get_random_img_url` multiple times in their chat prompts to generate several different placeholder images, quickly filling out the visual layout without needing actual art assets. ### Preparing team documentation A technical writer needs a quick way to document various status codes. They run `list_ducks` first, see that 200 and 500 ducks are available, then systematically use `get_http_duck` for each code. The resulting visual guide is much more engaging than raw text. ### Internal team morale boost During a stressful daily standup call where the system hiccupped, someone asks their agent for 'a random duck.' They use `get_quack` to get a fun image. It breaks tension and makes the technical discussion feel lighter. ## Benefits - Stop typing out error codes. Using `get_http_duck` instantly generates a duck that visually represents failure states (like 404), making documentation clearer and faster. - Need quick placeholders? The `get_random_img_url` tool gives you a direct link to any random asset immediately, bypassing the need for local file paths in your mockups. - Avoid guessing what assets exist. Running `list_ducks` shows the entire available pool of files—from specific status codes to general ducks—so you know exactly what you can ask for. - Debugging is funnier now. Instead of just saying '500 Error,' your agent runs `get_http_duck` and drops a duck that makes the error memorable during standups. - Need consistency? If you want to reference an asset by its number, use `get_specific_duck`. This is better than relying on random chance when accuracy matters. ## How It Works The bottom line is: you talk to your agent, it calls the right API function, and you get a visual asset back—no code needed on your end. 1. First, connect your AI client (Claude, Cursor, etc.) to RandomDuck MCP. You'll use 'public' as the token. 2. Next, ask your agent for what you need—for example, 'Show me the duck for HTTP 404' or 'Get a random duck'. 3. The agent executes the appropriate tool (`get_http_duck` or `get_random_duck`) and returns the image URL directly into your chat output. ## Frequently Asked Questions **How do I get a random duck image using get_random_duck?** You just ask your agent to run `get_random_duck`. It returns a URL for a completely random asset. If you only need the link and not the full content, use `get_random_img_url` instead. **Which tool do I use if I want the 404 duck?** Use `get_http_duck`. You pass '404' as the argument. This is the specific function for visualizing standard HTTP error codes, making sure you get a consistent asset. **What if I want to see all available duck assets?** Run `list_ducks`. This tool shows every filename and category currently in the library. It’s your master index for knowing what ducks are out there. **Can I use get_specific_duck if I don't know the file number?** No, `get_specific_duck` requires the exact asset identifier. You must run `list_ducks` first to obtain that specific duck's number or filename. **When I use `get_http_duck`, how does the server handle invalid or non-standard HTTP status codes?** The system returns an error message when you request a code outside the defined range (like 999). You must provide a recognized three-digit code, such as 200 or 503, for the tool to successfully retrieve the visual asset. **Is there any performance difference between using `get_random_duck` and calling `get_random_img_url`?** No. Both tools draw from the same pool of assets, so performance is consistent. The main difference is that `get_random_duck` returns a rich asset (GIF or image), while `get_random_img_url` sends only the direct URL string. **If I use `upload_duck`, what are the size constraints and guidelines for new images?** You must upload JPG format files that meet minimum resolution requirements. The tool queues your submission for human review by Mod Mallard before it becomes publicly accessible. **What is the required token or authentication when using `get_quack` in my AI client?** You don't need a specific API key. For public access to random ducks, simply use 'public' as your token within any compatible MCP client. **Can I get a duck for a specific HTTP error code?** Yes! Use the `get_http_duck` tool and provide the status code (e.g., 404 or 500). The agent will return the URL of a duck representing that specific HTTP state. **How do I see all the ducks available in the library?** You can use the `list_ducks` tool. It will return lists of all available JPG and GIF filenames, as well as the supported HTTP status codes. **Can I upload my own duck images to the server?** Absolutely. Use the `upload_duck` action with your base64 encoded image data. Your submission will be sent for review by the community moderators.