MCP
Foreword: What is MCP?
MCP stands for Model Context Protocol and is a standard for AI models or agents to access external tools and APIs. It defines a structured way for models to interact with APIs, including how to authenticate, make requests, and handle responses.
Our MCP philosophy
At Riddle, we are committed to making all API functionalities available via the MCP, enabling seamless integration of Riddle with AI models and agents. This means that any action you can perform via our API can also be performed by an AI model using the MCP, i.e., allowing for dynamic content creation, analysis, and management of Riddle content through AI.
We are currently not covering all Creator/API functionalities; consider this MCP version as an alpha. In the future we aim to provide more functionality, especially those currently only available via the Creator (e.g. updating / adding / removing Riddle blocks), so stay tuned for updates on that front!
How to use
Currently the MCP is only usable with clients that support sending custom headers along every MCP request. For debugging purposes a tool like Model Context Protocol Inspector is ideal to inspect the requests sent by the model and the responses returned by the API.
Before you can start sending requests to the MCP, you need to establish a connection by authenticating with your MCP key. To learn how MCP / API keys are created / work, you can refer to the API Getting started > Authentication guide. Best suited are personal MCP keys: With these keys you have access both to your personal project and to all projects in which you have the corresponding AI permissions.
Note: It is very important to create a MCP key, not a regular API key. Regular API keys will not work with the MCP and will return an error - make sure you have the correct permissions to use MCP keys. If you do not have the right permissions, you will only see one button, "Create API key". In this case contact your project administrators to get the necessary permissions or ask them to create an MCP key for you.
Example setup (in Model Context Protocol Inspector)
- Transport type → Streamable HTTP
- URL →
https://www.riddle.com/creator/api/v3/mcp - Connection Type → Via Proxy
- Custom Headers →
{"Authorization": "Bearer [your Riddle MCP key]"}
Setup illustration
Response Format
All responses from the MCP will adhere to the same schema as specified in the API docs for the corresponding endpoint.
E.g. the riddle_get tool will return a response with the same schema as the GET /riddle/{riddle_uuid} API endpoint, including all details about the riddle content, design, etc.
Available Tools & Resources
Note: You can use standard MCP functionality to list tools and resources available to the model; this will include more verbose information, e.g. API parameters. Below is a short summary, but make sure to fetch the MCP's current capabilities to get the most up-to-date information.
Tools (32)
| Tool | Description |
|---|---|
| ping | A simple tool that returns "Pong". Can be used to test connectivity and authentication to the MCP. |
| whoami | Returns information about the current API key: the authenticated user (ID, email, name) and the associated project/team if using a project API key. Useful to verify authentication and retrieve your user ID or project ID. |
| project_list | Returns a list of all projects this token has access to. If it is a project API token, only the project linked to the token will be returned. |
| project_get | Returns a single project by its project ID. The project ID can either be obtained through the project list tool or by taking the "team" property of the riddle_get tool. |
| riddle_list | Returns a paginated list of Riddles from a single project. Use projectId to specify the project, or omit it to list from the personal project. For Riddles across all projects, use riddle_account_list instead. |
| riddle_account_list | Returns a paginated list of all Riddles across the entire account – both the personal project and all team projects the user has access to. Use riddle_list to filter by a single project instead. |
| riddle_get | Gets a single Riddle by its UUID. Returns the full Riddle data including content, settings, and metadata. |
| riddle_get_embed_code | Gets the HTML embed code for a Riddle by its UUID. The Riddle must be published to retrieve the embed code. |
| riddle_publish | Publishes a Riddle by its UUID; meaning the Riddle will be available via its public URL. |
| riddle_unpublish | Unpublishes a Riddle by its UUID; meaning the Riddle will no longer be available via its public URL. |
| riddle_rename | Renames a Riddle with the specified UUID. Returns the updated Riddle data. |
| riddle_qr_code | Generates a QR code for a Riddle by its UUID. Returns a base64 encoded SVG image. The Riddle must be published. |
| riddle_delete | Deletes a Riddle by its UUID. Only Riddles created via the Builder API can be deleted. |
| riddle_builder_quiz | Builds a Quiz with structured parameters. |
| riddle_builder_poll | Builds a Poll with structured parameters. |
| riddle_builder_personality | Builds a Personality Test with structured parameters. |
| riddle_builder_form | Builds a Form with structured parameters. |
| riddle_builder_predictor | Builds a Predictor with structured parameters. |
| riddle_builder_leaderboard | Builds a Leaderboard. Connect quizzes or predictors that have Name and Email fields. |
| riddle_builder_minigame | Builds a Minigame. Supports SlotMachine, WheelSpinner, and Sudoku block types. |
| riddle_aiGenerate_usage | Returns the current AI usage and maximum allowed usage for the authenticated user. |
| riddle_aiGenerate_quizFromTopic | Creates a Quiz from a topic via the Riddle AI. Processing is asynchronous – the returned UUID can be used with riddle_get to check status. Check riddle_aiGenerate_usage first to ensure credits are available. |
| riddle_aiGenerate_pollFromTopic | Creates a Poll from a topic via the Riddle AI. Processing is asynchronous – the returned UUID can be used with riddle_get to check status. Check riddle_aiGenerate_usage first to ensure credits are available. |
| riddle_aiGenerate_personalityFromTopic | Creates a Personality Quiz from a topic via the Riddle AI. Processing is asynchronous – the returned UUID can be used with riddle_get to check status. Check riddle_aiGenerate_usage first to ensure credits are available. |
| riddle_aiGenerate_quizFromUrl | Creates a Quiz from a URL via the Riddle AI. The URL content is scraped and used to generate questions. Processing is asynchronous – the returned UUID can be used with riddle_get to check status. |
| riddle_aiGenerate_quizFromUrls | Creates a Quiz from multiple URLs via the Riddle AI. Content from all URLs is scraped and combined to generate questions. Processing is asynchronous – the returned UUID can be used with riddle_get to check status. |
| riddle_aiGenerate_pollFromUrl | Creates a Poll from a URL via the Riddle AI. The URL content is scraped and used to generate poll questions. Processing is asynchronous – the returned UUID can be used with riddle_get to check status. |
| stats_fetch | Returns aggregated statistics (views, starts, submissions) for a single period. Omit dateFrom/dateTo for alltime stats, provide both for a specific date range, or only provide one of them for an open-ended date range. |
| stats_overview_fetch | Returns statistics divided into daily intervals for the given date range. Useful for dashboards, graphs, and trend analysis. Both dateFrom and dateTo are required. |
| stats_riddle_breakdown | Returns a detailed stats breakdown for a specific Riddle, including titles, choices, views, time spent, and submissions. |
| stats_user_breakdown | Returns a stats breakdown for the authenticated user across all accessible projects. Requires a user API key – will fail with project API keys. Use stats_project_breakdown for single-project stats instead. |
| stats_project_breakdown | Returns a stats breakdown for a specific project. |
Resources (6)
| Resource | URI | Description |
|---|---|---|
| getting-started | riddle://reference/getting-started | Overview of the Riddle MCP server: available tool categories, common workflows, and authentication model. |
| riddle-types | riddle://reference/riddle-builder/riddle-types | All 7 Riddle types with their required/optional build fields, result structure, and documentation links. |
| block-types | riddle://reference/riddle-builder/block-types | Question and content block types per Riddle type with required properties and item formats. |
| form-field-types | riddle://reference/riddle-builder/form-field-types | All 15 form field types for the FormBuilder block with their properties and configuration options. |
| result-blocks | riddle://reference/riddle-builder/result-blocks | All 9 result page block types with their properties, format options, and styling configuration. |
| ai-languages | riddle://reference/ai/languages | All available language codes for AI Riddle generation (used in the "language" parameter of riddle_aiGenerate_* tools). |
Troubleshooting
If you encounter any issues while using the MCP, here are some common troubleshooting steps:
- API authentication failed: Make sure your API key is still valid (re-create if in doubt) and that you are including it correctly in the Authorization header as
Bearer [your API key]. - Missing API permissions: Check if your user role has the necessary AI permissions to access the desired projects and perform the intended actions. If you do not have permission to modify roles, ask your account administrators to grant you the required permissions.
... Still not solved? Please reach out to our support team with details about the issue, either via our support chat or via email, including any error messages received and the steps you have already taken to troubleshoot.
Next steps
Now that you have established a connection to the MCP and are familiar with the available tools and resources, you can start building and analyzing your AI-powered Riddle application. Whether you want to create dynamic quizzes, analyze content performance, or generate new Riddles with AI, the MCP provides a powerful interface to leverage Riddle's capabilities in your projects. Happy building!
Want to continue reading? Read the following API sections to understand the MCP tools in more detail and see example requests and responses for each of them:
- Look at the specification of all available API endpoints: Find out what you can do with the Riddle API.
- Stats API: Use the Riddle Stats API to retrieve stats for any of your Riddles, projects, or for your personal project.
- Builder API: Use the Riddle Builder API to create Riddles programmatically with defined build configurations.
- Generative AI API: Use the Riddle Generative AI API to create Riddles programmatically based on topics and URLs.