MCP
The Model Context Protocol (MCP) is a standard that lets AI models and agents call external tools and APIs. Riddle's MCP exposes our API to AI agents, so any action you can do via the API – such as listing, building, editing, and analyzing Riddles – can be triggered from an AI chat.
How to use
When using the Riddle MCP, you have two options for authentication:
- Preferred: Via public MCP URL in Claude (using the CIMD (Client ID Metadata Document) protocol)
- Via MCP key embedded in the URL
Via public MCP URL in Claude
- To add the Riddle MCP to your Claude account, navigate to Settings > Connectors > Add custom connector.
- To add the Riddle MCP to your Claude organization, navigate to Organization settings > Connectors > Add > Custom > Web connector.
In both cases the following dialogue will show:
Enter the following:
- Name: Riddle MCP
- URL:
https://www.riddle.com/creator/api/v3/mcp
After clicking on add, you are almost ready to use the MCP in your Claude chats: Click on connect afterwards to link your Riddle account with Claude and if necessary, you'll have to log in. Once you're done with this, you can try asking Claude to list the latest, published Riddles from your account to test the connection. You can also use the whoami tool to verify your account and project access.
Via MCP key
If you wish to use the MCP with an MCP key, create one on the API keys page (see the Authentication guide for details). Please make sure to pick a MCP key – regular API keys will not work and will return an error. Personal MCP keys are best suited: they give you access both to your personal project and to all projects in which you have the corresponding AI permissions. If you can only create normal API keys, your user role is missing the required permissions – ask a project administrator to grant them or to issue an MCP key for you.
Once you have your key, append it to the MCP URL as a path segment: https://www.riddle.com/creator/api/v3/mcp/[MCP_KEY]
Replace [MCP_KEY] with your actual key, then add this URL as a custom connector in Claude (same steps as above).
Please note that accessing the MCP via a configured MCP key is inferior to the CIMD option. It requires you to embed your key in the URL, and it is less flexible: you need to create a new MCP key for every Riddle account you want to access. With CIMD, each user authorizes with their own Riddle account instead, so no account has to be pre-configured in the URL.
Available Tools, Resources & Prompts
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 (62)
The 62 tools fall into nine categories:
| Category | Tools |
|---|---|
| Utility & Account | 2 |
| Documentation | 1 |
| Projects | 3 |
| Riddle management | 14 |
| Builder API | 11 |
| Templates | 5 |
| Question banks | 19 |
| Design & palettes | 2 |
| Statistics | 5 |
Utility & Account (2)
Test connectivity and check the context of your API key.
| Tool | Description |
|---|---|
| ping | Connectivity and authentication test – simply returns "Pong". |
| whoami | Returns information about the current API key: the authenticated user (ID, email, name) and the linked project/team, if any. Useful to verify authentication and retrieve your user ID or project ID. |
Documentation (1)
| Tool | Description |
|---|---|
| reference_get | Reads the documentation of the MCP server itself: the block types, form field types, result blocks, palette values, response shapes, per-entity defaults and the concept documents the other tools expect. Every riddle://reference/... URI mentioned in a tool description, a tool response or an error message is a topic of this tool, and the content is identical to reading that URI as an MCP resource, so a client that cannot read resources can read them through this tool instead. Start with riddle://reference/index, which lists every address with its exact size. At most 8 topics per call, and riddleType / blockTypes / fieldTypes narrow the large documents before they are sent; see their sizes. |
Projects (3)
List projects and fetch project details.
| Tool | Description |
|---|---|
| project_list | Paginated list of the projects this token has access to (25 per page, 100 max), with a pagination object to page through accounts with many projects. If it is a project API token, only the project linked to the token will be returned. Returns a trimmed summary (id, name, image) per project. |
| project_get | Fetches a single project by its project ID. |
| project_get_settings | Returns the default Riddle settings of a project - the settings every new Riddle in it starts from, as defaultRiddleSettings (the draft the project owner edits) and publishedDefaultRiddleSettings (what Riddles actually inherit). A large, deeply nested payload - use project_get for a project's name, image and permissions. |
Riddle management (14)
Find, read, and manage existing Riddles.
| Tool | Description |
|---|---|
| riddle_list | Paginated list of Riddles from a single project – filterable by type, status, tags, origin (API created vs. created by hand), and search term; sortable. For Riddles across all projects, use riddle_account_list instead. |
| riddle_account_list | Paginated list of Riddles across the entire account – the personal project plus all team projects the user has access to. |
| riddle_get | Fetches a single Riddle by its UUID as a build configuration: {uuid, type, modifiedAt, build, nextBlockId, warnings, published, context}. build is the same builder config the builder tools accept, so a Riddle can be read, edited and rebuilt; anything it cannot express is reported in warnings. nextBlockId is the block ID a new block may claim in an edit. published describes the live version: null when never published, {"status": "identical", "isLive": true} when the live Riddle is exactly what build describes, and {"status": "differs", "isLive": ..., "build": ..., "warnings": ...} (spelled out in full) when there are unpublished changes. status compares content, isLive says whether the Riddle is online at all, and the two are independent: unpublishing does not clear published back to null (the last published content stays stored), so an unpublished Riddle answers {"status": "identical", "isLive": false}. Read isLive, not status, for "is this online right now". context adds title, features, origin, published state, the Riddle this one was copied from (duplicated), project and preset information. Reads several Riddles in one call with UUIDs, and omit leaves parts of the response out, the only way to make it smaller. |
| riddle_rename | Renames a Riddle (new title by UUID). |
| riddle_publish | Publishes one Riddle (UUID) or up to 100 at once (UUIDs) – each becomes available via its public URL. For a single Riddle the answer is the same envelope riddle_get returns, with the new state under context.published, and omit shrinks it exactly as it does there; for many it is the bulk envelope {bulk, operation, summary, results} with one entry per Riddle. A bulk publish is not atomic and never gives up early: a Riddle that cannot be published is reported as that entry's error while all others are still published. |
| riddle_unpublish | Takes one Riddle or up to 100 offline – the public URL is no longer reachable. A Leaderboard with active connections cannot be unpublished; use riddle_delete on it instead, which is always allowed and cleans the connections up. Same single/bulk response shapes and the same omit support as riddle_publish. |
| riddle_delete | Deletes one Riddle (UUID) or up to 100 at once (UUIDs). Only Riddles created via the builder, created from a template with riddleTemplate_use, or generated by the Riddle AI can be deleted – context.origin.apiManageable on riddle_get tells you upfront whether a Riddle qualifies. A bulk delete is not atomic and never gives up early. Order does not matter: a Riddle that another item of the same batch still references (a Leaderboard's connected Quiz, a FormSelect's Form) is retried once automatically after the rest of the batch has run, so only a failure that survives the retry is reported as an error. |
| riddle_get_embed_code | Returns the HTML embed code of a published Riddle. |
| riddle_qr_code | Generates a QR code (base64-encoded SVG) for a published Riddle. |
| riddle_move | Moves up to 100 Riddles into another project (or into the personal project). All-or-nothing: Riddles that reference each other - a Quiz and its Leaderboard, an embedded Form - have to move together, and the error names the ones to add. Needs the transfer permission in both projects. Tags are re-pointed to the destination scope; a tag left behind in the source scope is removed once nothing - no Riddle, no question bank - uses it there any more. The Riddle keeps its own design: a move does not switch it to the destination project's default preset. |
| riddle_move_check | The same check without moving anything: which Riddles are movable, which are blocked and by what, the UUIDs to add, and the projects the whole set could go to. |
| riddle_tag_list | The tags of a project with their usage count ({id, name, count}) - tags are per project. count only counts Riddles: a tag shared with a question bank can show count: 0 and still be in use there. Gives you the tag IDs the riddle_list filters accept. |
| riddle_tag_add | Adds a tag to one Riddle or up to 100 at once, by tag name (created if the project does not have it yet) or tag ID. |
| riddle_tag_remove | Removes a tag from one Riddle or up to 100 at once. The tag itself is only deleted from the project once nothing - no Riddle, no question bank - uses it any more. |
Builder API (11)
Create and edit Riddles with structured parameters (blocks, results, logic, presets, publish settings).
| Tool | Description |
|---|---|
| riddle_builder_quiz | Builds a Quiz – question blocks (SingleChoice/MultipleChoice/TextEntry/Order/Flashcard/TypeRush/GuessIt), results with percentage ranges, optional branching logic and leaderboard connection. |
| riddle_builder_poll | Builds a Poll – block types include SingleChoice, Matrix, Order, Upvote, NPS, RateIt, Swiper, Reaction, TextEntry, and TierList; optional branching logic. |
| riddle_builder_form | Builds a Form – FormBuilder blocks with field mapping (e.g. Email, Name); result page with dynamic variables such as %fieldname. |
| riddle_builder_personality | Builds a Personality quiz – questions with score arrays per answer, at least 2 personalities with title/description/media. |
| riddle_builder_predictor | Builds a Predictor – blocks of type PickTheWinner or GuessTheScore, optional leaderboard connection. |
| riddle_builder_minigame | Builds a Minigame – SlotMachine, WheelSpinner (win/loss/free spin with percentages), or Sudoku. |
| riddle_builder_leaderboard | Builds a Leaderboard – connects up to 10 Quizzes, Predictors, or Minigames (Name and Email fields required); optional email validation. |
| riddle_builder_story | Builds a Story – general content blocks (Content/Ad/Quote), the InteractiveGraphic block and form fields, one optional result page, no questions or scoring; optional linear-only branching logic. |
| riddle_builder_placeholder | Builds a Placeholder – a Riddle with no content of its own, only a routing rule saying which other Riddle (or which Riddle carrying a given tag) is shown in its place. Needs the Placeholder feature. The rule is stored, not evaluated here, and comes back re-sorted and window-trimmed rather than verbatim. |
| riddle_builder_update | Edits an existing Riddle of any type as a merge, not a rebuild: only what you send changes. Blocks are addressed by their ID and can be added ("$create": true), removed ("$delete": true) or reordered (blocksOrder); title, result/results, logic, a Personality Test's personalities, a Leaderboard's riddleConnections and a Placeholder's conditions are replaced as a whole when sent and kept when omitted, while preset and publishSettings merge per key, so only the settings you send change. Only Riddles created with the builder or generated by the Riddle AI can be edited - check context.origin.apiManageable from riddle_get first, which is also where the block IDs are. Returns the edited Riddle in the same envelope riddle_get returns. See Editing Riddles. |
| riddle_builder_validate | Dry-runs creates and/or edits – 1 to 20 per call, mixed freely – without creating or changing anything: each entry of builds is validated exactly as the real call would validate it, against a scratch Riddle that is discarded before the answer. Nothing is persisted, published or queued. Media URLs are still checked for reachability with a live request (the file is never downloaded), so an unreachable URL is rejected here too. The answer is {valid, summary, items} with one entry per item, in the order sent, each carrying either the build it would end up with or the errors it would be rejected with – one item's outcome never affects another's. Needed plan: Business or Enterprise. See Validating build configurations. |
Templates (5)
Reuse a Riddle as the starting point for new ones – your project's own templates and Riddle's public ones. A template is a copy taken at one moment: the Riddle it was made from keeps living its own life.
| Tool | Description |
|---|---|
| riddleTemplate_create | Stores an existing Riddle as a template of its project (or of you, for a personal Riddle), so new Riddles can be created from it. It copies what the Riddle currently has stored, published or not; later changes to the Riddle do not reach the template. Requires the template-create permission. |
| riddleTemplate_list | The templates of a project (or your personal ones) – the ones your Riddles were made into, not Riddle's public ones. Filterable by Riddle type. Returned without the build configuration. |
| riddleTemplate_publicList | Riddle's public, ready-made templates, grouped by category – so calling it without arguments is also how you learn which categories exist. Also filterable by type. An unknown category is rejected with an error naming the categories that are actually allowed, rather than silently returning nothing. |
| riddleTemplate_get | A single template including its build configuration – the same build shape riddle_get returns and the builder tools accept. This is how a template is adapted rather than copied: edit the returned build and build it with the riddle_builder_<type> tool of the template's type, passing the template's id as templateId so the new Riddle is still recorded as coming from it (and starts out on the template's whole preset, layout included). A template whose content has no build-configuration equivalent comes back with an empty build and a warning saying so. |
| riddleTemplate_use | Creates a new Riddle from a template as an unchanged copy – content, settings and design preset – in one call, and records the lineage: reading it back reports the template's Riddle under context.duplicated. The new Riddle is a draft, so call riddle_publish to make it live, and it counts as programmatically created, so riddle_builder_update, palette_customize and riddle_delete work on it (context.origin.apiManageable). Requires the template-use permission plus Riddle-create permission in the target project. |
Question banks (19)
Manage the reusable question pools a QuestionBank block of a Quiz or Poll draws from. A bank belongs to one project and to one Riddle type, and its items have a draft/published split of their own: a QuestionBank block always draws from a bank's published state, so a bank has to be published before its questions show up in a Riddle. See Question banks.
| Tool | Description |
|---|---|
| questionBank_create | Creates a new, empty bank for a Riddle type (Quiz or Poll) in a project. Its id is what a QuestionBank block references as questionBankId. |
| questionBank_list | Paginated list of the banks of a project (12 per page, 50 max), filterable by search term and tags. |
| questionBank_templateList | The built-in template banks anyone can duplicate to start with real content. A template that was never published reports itemCount: 0 – judge its real size by draftItemCount. |
| questionBank_get | A single bank: title, riddleType, tags, notes, categories/blockTypes and whether it has unpublished changes. Works on a template id too. |
| questionBank_getItems | The items (draft content) of a bank, filterable by search term, blockType, category or difficulty range. Returns everything unless you page it – unlike questionBank_list. |
| questionBank_rename | Renames a bank. Title and notes are metadata outside the draft/publish split, so this takes effect immediately. |
| questionBank_updateNotes | Replaces the bank's internal plain-text notes – for its maintainers, never shown to participants. |
| questionBank_duplicate | Copies a bank (or a template) with all of its items into a new, independent bank, optionally in another project. |
| questionBank_publish | Makes every item's draft content its published content – what a QuestionBank block actually draws. Also the moment a pending delete of a published item is purged for good. |
| questionBank_discardChanges | Resets every item back to its last published state, undoing pending deletes as well. Irreversible. |
| questionBank_delete | Deletes a bank and all of its items. A QuestionBank block still referencing the id afterwards simply draws nothing. |
| questionBank_addItem | Adds one question to a bank's draft. Call questionBank_blockTypeColumns first – there is no universal item shape. |
| questionBank_updateItem | Replaces an item's content entirely (blockType, category, difficulty and all columns). blockType is immutable. |
| questionBank_deleteItem | Deletes one item. A never-published item is gone immediately; a published one keeps being drawn live until the next questionBank_publish. |
| questionBank_blockTypeColumns | Every blockType valid for a bank of a given Riddle type, with the exact columns shape addItem/updateItem expects for it – a Quiz SingleChoice and a Poll SingleChoice differ. |
| questionBank_tagList | The bank tags of a project with usage counts – the tag IDs questionBank_list filters by. Separate from Riddle tags. |
| questionBank_addTag | Tags a bank by tag name (created if new) or tag ID. |
| questionBank_removeTag | Removes a tag from a bank; a tag no bank uses any more is deleted from the project. |
| questionBank_riddleBlockItems | Previews which items a QuestionBank block of an existing Riddle would draw right now – criteria matching too little inventory are only a pre-publish warning, so this is how to catch it. |
Design & palettes (2)
Read and change the design (colors, fonts, buttons, background) of a Riddle.
| Tool | Description |
|---|---|
| palette_get | Reads the palettes of a Riddle: every palette it can use (including the ones inherited from the account or project default preset) with all values, which palette is selected, which values this Riddle overrides, and the built-in palettes that can be used as a starting point. |
| palette_customize | Changes the palette of a single Riddle via a path ⇒ value map, e.g. {"bgColor": "#ffffff", "font.name": "Roboto"}. An inherited palette is never changed for other Riddles - the values are stored as an override on this Riddle, and built-in palettes are duplicated into a Riddle-owned copy automatically. A palette change does not update the Riddle's modifiedAt, matching the Riddle Creator, which does not stamp modifiedAt for a design change either. The new design is only visible on the embedded Riddle after publishing it again. Like riddle_delete, this only works on Riddles created via the builder or generated by the Riddle AI. |
Statistics (5)
Views, starts, and submissions on user, project, and Riddle level.
| Tool | Description |
|---|---|
| stats_fetch | Aggregated stats (views, starts, submissions) for a single period – namespace: project, user, or riddle; omit the dates for all-time stats. |
| stats_overview_fetch | Stats in daily intervals for a given date range – ideal for dashboards, graphs, and trend analysis. |
| stats_riddle_breakdown | Detailed breakdown for a specific Riddle – titles, answer choices, views, time spent, and submissions. |
| stats_project_breakdown | Stats breakdown for a specific project. |
| stats_user_breakdown | Stats breakdown for the authenticated user across all accessible projects – requires a user API key (will fail with project API keys). |
Resources (67 documents)
Every reference document has an address of the form riddle://reference/..., and each address is readable two ways with identical content: as an MCP resource (resources/read), and through the reference_get tool (topics: ["riddle://reference/..."], up to 8 addresses per call). Most clients do not expose resources to the model, which is what the tool is for.
The catalogue has three parts: an index, twelve single documents, and three families that generate one address per entity.
Start at the index
| Resource | URI | Size | Description |
|---|---|---|---|
| reference-index | riddle://reference/index | 4 KB / ~1k tokens | Every address of this server with a one-line summary and its exact size in bytes, the generated per-entity addresses included. |
Read it first when you do not know which document you need. It is by far the smallest, its sizes are the same numbers resources/list advertises, and they are measured on the JSON a read actually returns, so a plan made from the index is a plan that holds.
Single documents (12)
One written document each, at a fixed address.
| Resource | URI | Size | Description |
|---|---|---|---|
| getting-started | riddle://reference/getting-started | 6 KB / ~1.4k tokens | What the server is for, the two API key types, the guided prompts, and the addresses of the concept documents. Start here when you do not know which tool to reach for |
| response-format | riddle://reference/response-format | 4 KB / ~1k tokens | The {uuid, type, modifiedAt, build, nextBlockId, warnings, published, context} envelope every Riddle-returning tool answers with, and the bulk envelope |
| riddle-types | riddle://reference/riddle-builder/riddle-types | 15 KB / ~3.9k tokens | All 9 Riddle types with their required and optional build fields, result structure and scoring settings |
| block-types | riddle://reference/riddle-builder/block-types | 48 KB / ~12k tokens | Every question and content block type per Riddle type. The reference for writing blocks |
| form-field-types | riddle://reference/riddle-builder/form-field-types | 7 KB / ~1.7k tokens | All 18 form field types of the FormBuilder block |
| result-blocks | riddle://reference/riddle-builder/result-blocks | 12 KB / ~3k tokens | All 12 result page block types with their properties, format options and styling |
| palette-fields | riddle://reference/palette/fields | 15 KB / ~3.8k tokens | Every palette value palette_customize accepts, where it is used and which CSS variable it renders into |
| palette-built-in | riddle://reference/palette/built-in-palettes | 22 KB / ~5.6k tokens | The built-in palettes with all of their values, as starting points for a custom one |
| palette-fonts | riddle://reference/palette/fonts | 6 KB / ~1.4k tokens | The font families available as font.name, plus self-hosted and Google/Typekit fonts |
| publish-defaults | riddle://reference/publish-defaults | 3 KB / ~0.8k tokens | The resolved default of every publish.<name> setting a read-back leaves out. One address, because they are the same for every Riddle type |
| form-field-defaults | riddle://reference/form-field-defaults | 22 KB / ~5.7k tokens | What every form field type accepts and defaults to, keyed by field type. fieldTypes narrows it to the ones you are building |
| question-bank-overview | riddle://reference/question-bank/overview | 4 KB / ~1.1k tokens | What a question bank is, its draft/publish model, and the filters a QuestionBank block draws with |
Families (3)
A family is a URI template. Replace the {variable} with a member name to get an address, for example riddle://reference/block-defaults/SingleChoice. Every member name and its exact size is listed in the index.
| Family | URI template | Addresses | Total size | Description |
|---|---|---|---|---|
| block-defaults | riddle://reference/block-defaults/{blockType} | 27 | 46 KB | Per block type: the constraint set its build configuration is checked against (types, required properties, enum values, sizes, whether a collection merges by id) and the resolved default of every property a read-back omits. Both generated from the block itself. Members: Ad, Content, Quote, SingleChoice, MultipleChoice, TextEntry, Flashcard, Order, TypeRush, GuessIt, QuestionBank, FormBuilder, FormField, Upvote, Matrix, NetPromoterScore, Swiper, RateIt, Reaction, TierList, ThisOrThat, GuessTheScore, PickTheWinner, SlotMachine, WheelSpinner, Sudoku, InteractiveGraphic |
| riddle-defaults | riddle://reference/riddle-defaults/{riddleType} | 9 | 28 KB | Per Riddle type: the constraint set of the Riddle-level properties, plus their defaults and the defaults of that type's preset. Members: the 9 Riddle types |
| concepts | riddle://reference/concepts/{concept} | 19 | 102 KB | One address per subject that is not an entity, so no entity document has to repeat it. Members: tools-by-category, workflows, editing, merge-semantics, defaults, response-envelope, warnings, bulk, common-block-properties, result-pages, form-fields-usage, logic, preset, publish, limits, unknown-properties, move-restrictions, question-bank-items, troubleshooting |
Note: The defaults families replaced the single riddle://reference/riddle-builder/block-defaults document, which held every block type of every Riddle type at once. One block type is now one address of 1 to 4 KB instead of a 53 KB read.
These documents are large - read them selectively
The whole catalogue is 339 KB, roughly 85k tokens, which is a substantial part of a model's context window before a single Riddle has been built. It is written to be read one address at a time, not loaded wholesale.
- Read the index first. It is ~1k tokens and it names the exact cost of everything else. Guessing which document you need and reading the wrong one costs far more than that.
- Never fetch everything.
reference_getaccepts at most 8 topics per call and rejects a longer list rather than returning a huge response. block-typesis the expensive one at ~12k tokens, followed byform-field-defaultsandpalette-built-in.riddle-typesplusblock-typesis the usual pair before building. Addform-field-typesonly for a Riddle with a form,result-blocksonly when you style a result page.- Read one entity, not a family. For defaults and constraints of the block you are configuring, read that block's own address (
riddle://reference/block-defaults/Matrix, ~1.5 KB), never the whole family. - Let the server slice the big ones.
reference_gettakesriddleType,blockTypesandfieldTypes: asking forblock-typeswithriddleType: ["Quiz"]drops every other type's blocks before the document is sent, while the shared conventions are kept. Filtering is far cheaper than receiving all 9 Riddle types and ignoring 8. These filters do not apply to the two defaults families, where the address already is the filter. - Prefer the cheaper source when there is one. For defaults of a block you have already built,
riddle_get's per-blockomittedDefaultscosts less than any reference read. For palettes,palette_getreturns the Riddle's actual values, sopalette-fieldsis only needed to look up a path you want to write. - Fetch once per session. Content changes only when the server is updated, so re-reading the same address in one conversation is pure token cost. The exception is a
VALIDATION_ERROR, where re-reading the relevant document is exactly the right move.
Guided workflows (12)
The MCP server also ships prompts: ready-made workflows that chain the tools above in the right order and ask you for the few things they cannot know (brand colors, the URL, which project). Pick one in your MCP client instead of describing the whole job yourself.
| Prompt | What it does |
|---|---|
| build_LeadGenQuiz | A lead-generation Quiz: entertaining questions, a form block that collects contact data before the result, optional double opt-in, published and ready to embed. |
| build_LeadForm | A standalone lead form (newsletter, registration, contact): the right field types, GDPR consent, double opt-in and a confirmation email. |
| build_ProductRecommender | A "which one fits me" product or plan recommender as a Personality test - each product is a personality, every result links to its page. |
| build_GatedContentStory | A gated content Story: teaser sequence, form gate in the middle, the asset behind it. |
| build_PredictorWithLeaderboard | A prediction game with a public ranking: a Predictor for the picks, a connected Leaderboard, and the scoring rules. |
| build_QuizContestWithLeaderboard | A quiz contest (e.g. a daily quiz) with a ranked Leaderboard: timed and scored questions, one entry per participant, a live ranking. |
| restyle_ToBrand | Restyles a Riddle to brand colors and fonts and publishes so the change reaches the embed. |
| organize_Library | Cleans up the library: find Riddles by filter, tag them, publish or unpublish the set, move them once the move is verified as possible. |
| localize_Riddle | Localizes a Riddle: read it as a build configuration, create the translated counterpart with the language set, keep the two in sync. |
| setup_DataLayerTracking | Instruments a Riddle for analytics: tracking networks, which events they fire, dataLayer pushes, publish. |
| analyze_CampaignPerformance | Reports on a campaign: collect its Riddles, pull views/starts/submissions plus the daily trend, turn it into a funnel and next steps. |
| optimize_Riddle | Optimizes a Riddle against its own stats: find the drop-offs, propose fixes, apply them as a merge edit and publish. |
Builder capabilities
The riddle_builder_* tools do more than their short descriptions suggest. Beyond the required title and blocks, most builder tools accept optional parameters that unlock the same power available in the Creator:
- Branching logic (
logic): Define a conditional flow over your blocks instead of a fixed linear order – route users to different blocks based on their answers, and merge paths back together. Supported by Quiz, Poll, and Form. - Design presets (
preset): Base the Riddle on an existing design/preset and override settings such as color palette, language, "remember user", and auto-open/auto-close dates. Supported by all types except Leaderboard. - Publish automation (
publish): Configure what happens on publish: double opt-in (DOI), email automation, tracking (pixels, analytics), data layer items, showcase visibility, and third-party integrations. Supported by all types except Leaderboard. Not to be confused with the builder tools' own top-levelpublishboolean, which publishes the Riddle right away. - Leaderboard connections (
leaderboard/riddleConnections): Attach a Quiz, Predictor, or Minigame to one or more leaderboards on creation, or create a Leaderboard that connects to existing Riddles (which must have Name and Email fields). - Publish & queue (
publish,queue): Publish the Riddle immediately after creation instead of leaving it as a draft, and/or process the creation asynchronously. - Project targeting (
project): Create the Riddle in a specific project, in your personal project, or in the currently selected project. - Reading Riddles back (
riddle_get): Every Riddle - not only the ones created via the API - can be read back as exactly this builder config, so an agent can inspect an existing Riddle, change a detail and rebuild it. What a builder config cannot express is listed inwarningsinstead of being silently dropped. - Editing Riddles (
riddle_builder_update): Change an existing Riddle instead of rebuilding it - blocks are addressed by their ID, only what you send changes, and blocks can be added, removed or reordered. Limited to Riddles created with the builder or generated by the Riddle AI (context.origin.apiManageable). See Editing Riddles. - Routing instead of content (
riddle_builder_placeholder): Build a Placeholder - embed one Riddle and decide by rule, tag or time window which Riddle actually shows. - Questions from a bank (
QuestionBankblock): Instead of authoring questions on the Riddle, let a Quiz or Poll draw them at view time from a question bank - filtered by category and difficulty, and optionally re-drawn on an interval. The bank itself is managed with thequestionBank_*tools. - Restyling (
palette_get/palette_customize): Read the full design of a Riddle and change individual palette values without touching the design of any other Riddle. - Checking before building (
riddle_builder_validate): Dry-run up to 20 creates and/or edits in one call - the same validation, nothing created or changed - to find out whether a configuration would be accepted, and why not, before spending a real call on it. See Validating build configurations. - Starting from a template (
riddleTemplate_*): Copy a template as-is withriddleTemplate_use, or read it withriddleTemplate_getand build the edited configuration with the builder tool of its type, passingtemplateIdso the new Riddle keeps the template's preset and its lineage.
Read riddle://reference/riddle-builder/riddle-types and block-types for the fields and formats each of these takes, the block's own riddle://reference/block-defaults/{blockType} address for its constraints and defaults, and riddle://reference/concepts/{concept} for the rules that span tools (editing, merging, presets, publishing, logic, limits). Listing the tools via standard MCP functionality gives you their parameter schemas.
Keeping the context small
An MCP conversation pays for every token it receives, and a few of these tools can answer with a lot. These are the levers – they matter for you in a chat, and they matter much more for an agent that runs unattended over many calls.
- Leave out what you will not read (
omit). Every tool that answers with a Riddle –riddle_get, allriddle_builder_*tools,riddle_publish,riddle_unpublish– acceptsomitto drop parts of the answer:build,warnings,nextBlockId,published,context, andbuild.omittedDefaults. That last one is the big one: the per-block default maps are most of a read-back, soomit: ["build.omittedDefaults"]alone can shrink the response by an order of magnitude. Only fetching a title?omit: ["build", "published", "warnings", "nextBlockId"]. - Scope the reference documents instead of loading them. The catalogue is ~85k tokens in total. Read
riddle://reference/index(~1k tokens) to see what each address costs, then askreference_getfor the one or two the current step needs, narrowed withriddleType/blockTypes/fieldTypes, and read them once per conversation. For a single block type, read its ownblock-defaultsaddress rather than a big document. See the note above. - One call instead of a loop.
riddle_get,riddle_publish,riddle_unpublish,riddle_deleteand the tag tools take a list (UUIDs, up to 100). One bulk call carries one envelope and one round of tool overhead rather than a hundred. - Edit instead of rebuilding.
riddle_builder_updateis a merge: to fix one question you send that one block, not the whole Riddle. Reading withomit: ["build.omittedDefaults"]and sending back the single block that changed is the cheapest edit loop there is. - Dry-run in batches.
riddle_builder_validatechecks up to 20 configurations in a single call. Twenty real builds that each fail cost twenty error responses – and twenty Riddles to clean up. - Filter at the source.
riddle_list,riddle_account_list,questionBank_listandquestionBank_getItemsall take filters, a search term and a page size. Narrowing the query beats fetching a broad list and discarding most of it. - Pick the smaller tool for the question.
project_getfor a project's name and permissions, notproject_get_settings(a deeply nested payload).riddle_get's per-blockomittedDefaultsfor the defaults of a block you already have, not a reference read.palette_getfor a Riddle's actual design, not the palette reference. - Start from a guided workflow. The prompts already chain the tools in the right order, so the model does not have to discover the sequence – and rediscover it after a wrong turn.
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.
Troubleshooting
If you encounter any issues while using the MCP, here are some common troubleshooting steps:
- API authentication failed: Make sure you are using an MCP key (not a regular API key – re-create if in doubt) and that the URL contains the actual key in place of the
[MCP_KEY]placeholder. - 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
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.