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 API key. To learn how API keys are created / work, you can refer to the API Getting started > Authentication guide. Best suited are personal API keys: With these keys you have access both to your personal project and to all projects in which you have the corresponding AI permissions.
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 API 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 (33)
| Tool | Description |
|---|---|
| ping | Tests connectivity and authentication to the MCP server. |
| whoami | Returns info about the currently authenticated user/project. |
| project_list | Lists all projects the token has access to with a MCP token. |
| project_get | Returns a single project by a specified ID. The project ID can be obtained from the project_list tool or by extracting any project (earlier: team) IDs returned by riddle_* or stats_* tools. |
| riddle_list | Lists Riddles with filtering by project, type, tags, status, search, and pagination. |
| riddle_account_list | Lists all Riddles in the account (personal + project), with filtering and pagination. |
| riddle_get | Gets a single Riddle by UUID with full content, settings, and metadata. |
| riddle_get_embed_code | Returns the HTML embed code for a published Riddle. |
| riddle_publish | Publishes a Riddle, making it available at its public URL. |
| riddle_unpublish | Unpublishes a Riddle, removing it from its public URL. |
| riddle_rename | Renames a Riddle by UUID. |
| riddle_qr_code | Generates a base64-encoded SVG QR code for a published Riddle. |
| riddle_delete | Deletes a Riddle (only those created via the Builder API). |
| riddle_builder_generate | Creates a Riddle using the full Builder API with raw JSON input. |
| riddle_builder_quickQuiz | Quickly builds a Quiz with structured parameters. |
| riddle_builder_quickPoll | Quickly builds a Poll with structured parameters. |
| riddle_builder_quickPersonality | Quickly builds a Personality Test with structured parameters. |
| riddle_builder_quickForm | Quickly builds a Form with structured field parameters. |
| riddle_builder_quickPredictor | Quickly builds a Predictor with structured parameters. |
| riddle_builder_quickLeaderboard | Quickly builds a Leaderboard connected to quizzes or predictors. |
| riddle_builder_quickMinigame | Quickly builds a Minigame (SlotMachine, WheelSpinner, or Sudoku). |
| riddle_aiGenerate_usage | Returns current AI usage and maximum allowed usage for the user. |
| riddle_aiGenerate_quizFromTopic | Creates a Quiz from a topic using Riddle AI (async). |
| riddle_aiGenerate_pollFromTopic | Creates a Poll from a topic using Riddle AI (async). |
| riddle_aiGenerate_personalityFromTopic | Creates a Personality Quiz from a topic using Riddle AI (async). |
| riddle_aiGenerate_quizFromUrl | Creates a Quiz by scraping a URL and generating questions via Riddle AI (async). |
| riddle_aiGenerate_quizFromUrls | Creates a Quiz from multiple scraped URLs via Riddle AI (async). |
| riddle_aiGenerate_pollFromUrl | Creates a Poll by scraping a URL and generating poll questions via Riddle AI (async). |
| stats_fetch | Returns statistics for a single period (alltime or date range). |
| stats_overview_fetch | Returns statistics divided into intervals, useful for dashboards and graphs. |
| stats_riddle_breakdown | Returns detailed stats for a specific Riddle (views, choices, time spent, submissions). |
| stats_user_breakdown | Returns stats breakdown for the authenticated user across all projects. |
| stats_project_breakdown | Returns stats breakdown for a specific project. |
Resources (4)
| Resource | URI | Description |
|---|---|---|
| riddle-types | riddle://reference/riddle-builder/riddle-types | Reference for all 7 Riddle types with their required/optional build fields and result structure. |
| block-types | riddle://reference/riddle-builder/block-types | Reference for question and content block types per Riddle type with required properties. |
| form-field-types | riddle://reference/riddle-builder/form-field-types | Reference for all 15 form field types with their properties and configuration options. |
| result-blocks | riddle://reference/riddle-builder/result-blocks | Reference for all 9 result page block types with styling and format options. |
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.