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:

1. Preferred: Via public MCP URL in Claude (using the CIMD (Client ID Metadata Document) protocol)
2. 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 (38)

The 38 tools fall into eleven categories:

The same grouping is readable from the server itself, with an explanation of what each category is for, at riddle://reference/concepts/tools-by-category.

Documentation (1)

Authentication & projects (5)

Test connectivity, check the context of your API key, and browse projects.

Riddle management (6)

Find, read, and manage existing Riddles. riddle_publish, riddle_delete, riddle_move and riddle_get each take one Riddle (UUID) or many (UUIDs) – see bulk calls.

Riddle Builder (3)

Create and edit Riddles with structured parameters (blocks, results, logic, presets, publish settings).

Design & palettes (2)

Read and change the design (colors, fonts, buttons, background) of a Riddle.

Media (2)

Get your own images, videos and audio into a Riddle – and out again. Read Working with media before the first call: an upload takes two steps, and the step you perform yourself needs outbound network access to *.riddle.com.

Tags (3)

Organize Riddles with tags. A tag belongs to a project, not to a Riddle, and Riddle tags and question bank tags are one set per project – the same tag applies to both and has the same id in both.

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.

Question banks (9)

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.

Embedding & sharing (1)

Statistics (1)

Views, starts, and submissions – one tool over two axes.

Bulk calls and dry-runs

riddle_get (up to 20), riddle_publish, riddle_delete, riddle_move and riddle_tag (up to 100 each) take UUIDs instead of UUID. The answer is then the bulk envelope {bulk, operation, summary, results} with one entry per Riddle – also for a one-element list, so a client can always send the same parameter and get the same shape back.

• Per-Riddle, not atomic: riddle_publish, riddle_delete and riddle_tag never give up early. One Riddle failing is reported as that entry's error while every other Riddle still goes through.
• riddle_move is the exception: it validates the whole set up front and moves nothing if any Riddle is rejected, because Riddles that reference each other can only move together. So pass exactly the set you intend to move – the same Riddle can be blocked on its own and movable inside a larger call.
• Ask before you act. The two operations you cannot take back report what they would do: riddle_move whenever no destination is named, riddle_delete with dryRun: true. Both run the same validation the real call runs and change nothing. When something is blocked, act on addUUIDs, add those UUIDs and check again.

Details: riddle://reference/concepts/bulk, and riddle://reference/concepts/move-restrictions for what makes a move impossible rather than merely denied.

Which writes are gated

Three writes only work on Riddles the API itself created: riddle_builder_update, riddle_delete and palette_customize. All three test the same flag – context.origin.apiManageable on riddle_get, origin on riddle_list – which is true for a Riddle built by riddle_builder_create or riddle_template_use, or generated by the Riddle AI, and false for one a user built by hand in the Creator. It is a permanent property of that Riddle: no API key, admin included, lifts it, and the only route to the same result is rebuilding the content through riddle_builder_create.

Every other write works on any Riddle the key may access, hand-built ones included: riddle_rename, riddle_publish (both directions), riddle_move, riddle_tag and riddle_template_create – as does everything under Media and Question banks, which are not Riddles at all. So check the flag before an edit, a delete or a restyle (riddle_list with origin: "api" returns exactly the Riddles all three work on, origin: "manual" the ones they do not), and do not check it before renaming, tagging, publishing or moving.

Resources (73 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 3 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, thirteen single documents, and three families that generate one address per entity.

Start at the index

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 (13)

One written document each, at a fixed address.

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.

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 on the order of 350 KB, roughly 90k 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_get accepts at most 3 topics per call and rejects a longer list rather than returning a huge response. The limit is deliberately small: block-types alone is the biggest response this server produces, and a call naming eight substantive topics exceeds what a client accepts inline - the answer is then no answer at all.
• block-types is the expensive one at ~12k tokens, followed by form-field-defaults and palette-built-in. riddle-types plus block-types is the usual pair before building. Add form-field-types only for a Riddle with a form, result-blocks only 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_get takes riddleType, blockTypes and fieldTypes: asking for block-types with riddleType: ["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-block omittedDefaults costs less than any reference read. For palettes, palette_get returns the Riddle's actual values, so palette-fields is 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.

Builder capabilities

The riddle_builder_* tools do more than their short descriptions suggest. Beyond the required title and blocks inside build, riddle_builder_create accepts optional fields 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-level publish boolean, 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 in warnings instead 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 (type: "Placeholder"): Build a Placeholder - embed one Riddle and decide by rule, tag or time window which Riddle actually shows.
• Questions from a bank (QuestionBank block): 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 the question_bank_* 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 (riddle_template_*): Copy a template as-is with riddle_template_use, or read it with riddle_template_get and build the edited configuration with the builder tool of its type, passing templateId so 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.

Working with media

Everything a Riddle shows has to live on Riddle's CDN, so a build configuration cannot point at a file on your machine – and an MCP call carries JSON, not a multipart body, so the server cannot take the bytes for you either. Three ways to reference a file:

Full property reference for all three: Use media.

There is no tool that browses the library. The id of a file the account already has is shown in the Creator's media library – ask the user for it rather than uploading the same file twice.

Uploading a local file

1. Mint a link. media_upload_link takes no arguments and returns {uploadUrl, expiresAt, singleUse, maxBytes, allowedTypes, usage, requiresNetworkAccessTo} – usage is the ready-to-run curl command.

2. Upload the file. POST it to uploadUrl as multipart/form-data under the field name file. The link carries its own signature, so no API key and no header are needed:

curl -F 'file=@/path/to/image.png' 'https://www.riddle.com/media-upload/<token>?_sig=<signature>'

The answer is everything needed to use the file, so no read-back call is required: {mediaId, type, width, height, size, folderId}.

3. Reference it by id.

"media": { "type": "Image", "mediaId": 4711, "altTag": "The Eiffel Tower in Paris" }

Never guess a URL for the file. A Riddle CDN URL passed as a plain url media is downloaded and re-hosted as a second, unrelated file – the account pays for the same image twice, and the library file records no usage, which makes an image in a live Riddle look safe to delete when it is not.

Step 2 leaves your environment, so it has to be allowed to reach the host named in requiresNetworkAccessTo – on production www.riddle.com, covered by the allowlist entry *.riddle.com. Use the wildcard rather than a hardcoded name; the host differs per environment. In Claude this is an organization setting only an admin can change. If the request is blocked, the fix is the allowlist, not another attempt: there is no second route in.

The rules a link comes with

So mint a link immediately before each upload rather than a batch up front, upload files one at a time, and never store or share a link – while it lives it is a credential that needs no other authentication.

Not every rejection costs you the link: everything judgeable without spending it – signature, permission, file size and type – is judged first, so an oversized file or a missing form field comes back as a plain error and the link stays usable. Anything that reaches the CDN spends it, success or not, and the answer is always a new link rather than a retry.

Where the file lands, and how to clean up

Uploads go into one fixed place per account – the folder "AI Uploads", tagged "AI Upload" – so the account owner can review everything an agent uploaded in a single view in the Creator. Agents cannot pick a folder or tag. The file is otherwise a normal library file: it belongs to the account (or project), counts against its storage, and any number of Riddles can use it.

media_delete removes a file again by mediaId, and frees the storage. It refuses while any Riddle still shows the file, naming those Riddles – so take it out of the Riddle first (riddle_builder_update, then riddle_publish so the change is live) and delete afterwards. "Unused" is a property of the file across the whole account: any one Riddle using it keeps it alive. The delete is permanent, the id is not reused, and a stored configuration still pointing at the file simply stops resolving – so an agent should ask before calling it.

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, all riddle_builder_* tools, riddle_publish in both directions, riddle_template_use – accepts omit to drop parts of the answer: build, warnings, nextBlockId, published, context, and build.omittedDefaults. That last one is the big one: the per-block default maps are most of a read-back, so omit: ["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 ~90k tokens in total. Read riddle://reference/index (~1k tokens) to see what each address costs, then ask reference_get for the one or two the current step needs (three at most per call), narrowed with riddleType / blockTypes / fieldTypes, and read them once per conversation. For a single block type, read its own block-defaults address rather than a big document. See the note above.
• One call instead of a loop. riddle_publish, riddle_delete, riddle_move and riddle_tag take a list (UUIDs, up to 100), riddle_get up to 20. One bulk call carries one envelope and one round of tool overhead rather than a hundred.
• Edit instead of rebuilding. riddle_builder_update is a merge: to fix one question you send that one block, not the whole Riddle. Reading with omit: ["build.omittedDefaults"] and sending back the single block that changed is the cheapest edit loop there is.
• Dry-run in batches. riddle_builder_validate checks 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 (in either scope), question_bank_list and question_bank_get_items all 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_get for a project's name and permissions, not project_get_settings (a deeply nested payload). riddle_get's per-block omittedDefaults for the defaults of a block you already have, not a reference read. palette_get for 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

A tool answers with its payload at the top level. There is no {success, data} envelope and no HTTP code around it: read build, never data.build. Success is the tool result's own isError flag. This is the one place the MCP deliberately differs from the REST API these tools call, which does wrap its responses that way – so a payload copied from the REST documentation has one level more than what an MCP client receives.

Apart from that wrapper, the content follows the REST schema of the corresponding endpoint, and three shapes cover almost everything:

A Riddle comes back as the build-configuration envelope {uuid, type, modifiedAt, build, nextBlockId, warnings, published, context} – from riddle_get, riddle_publish, riddle_template_use and every riddle_builder_* tool. None of them returns the raw stored Riddle, which is far too large for an inline MCP response, and none of them fails on content the build configuration cannot express: that is reported in warnings instead. Types are stable across calls, so a field that is an object is always an object – an empty map is {}, never [].

A listing comes back as {items, page, pageSize, total, hasMore}. items is always present and always an array – empty when nothing matched, never null. The paging fields are present exactly when the listing is paginated (riddle_list, project_list, question_bank_list, question_bank_get_items): page and pageSize as the call actually ran, total how many entries match the filters at all, hasMore whether another page follows. An unpaginated listing (riddle_template_list, riddle_tag_list, question_bank_list with scope: "templates") answers with items alone – the missing hasMore is what says "this is everything". No listing reports a count: the entries in one response are items.length. The one exception is riddle_template_public_list, which groups by category ({categories, total}), since discovering the categories is the point of that call.

A failed call answers with {success: false, error, message} instead of any payload – the one place success survives, because the same object also travels as a failed entry inside a bulk call that did not fail as a whole. error is a stable code to branch on, message is prose for the user. When the failure has more than one thing to say, validationErrors carries one {message, code, ...} entry per individual reason (each with whatever identifies the offending part – a blockId, a resultId, a field name) and validationWarnings the same shape for findings that did not cause the failure. Read validationErrors rather than the top-level message when it is present: it is the complete set of reasons, and the only way to fix them all in one pass. Both lists are absent when empty, never present as []. Branch on code, never on the message text.

Field by field: riddle://reference/concepts/response-envelope, plus /warnings, /publish and /bulk.

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.
• An upload cannot reach *.riddle.com: the upload is a request your own environment makes, so it must be allowed to reach the host in requiresNetworkAccessTo – in Claude an organization setting only an admin can change. Retrying will not help; see Working with media.
• An upload link no longer works: links live 5 minutes and are single-use, even when the upload failed after reaching the CDN. Mint a new one and upload right away.
• A tool is not there / has the wrong name: every tool was renamed to snake_case and a number of them were merged in favour of a mode argument. Look the old name up in Renamed and merged tools. If the agent still offers old names, reconnect the MCP so the client re-reads the tool list.
• The agent reads data.build and finds nothing: MCP answers are flat, with no {success, data} wrapper – see Response Format.
• A write is refused with "This Riddle was created in the Creator and can only be changed there" (RIDDLE_NOT_API_MANAGEABLE): Riddles created in the Creator can be read and updated through the MCP, but only a handful of write tools accept them – see Which writes are gated.

... 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.