# Riddle MCP server

> Build, edit, publish and analyze quizzes, polls, forms and personality tests in Riddle from an AI chat.

- Listing: https://mcp.tc/i/riddle
- Connect: use the server's own URL `https://www.riddle.com/creator/api/v3/mcp` (OAuth sign-in at the server); clients connect to it directly. The listing link is a page, not an MCP endpoint.
- Type: remote (Streamable HTTP)
- Auth: OAuth sign-in
- Category: [Marketing & SEO](https://mcp.tc/c/marketing-seo)
- Vendor: Riddle
- Homepage: <https://www.riddle.com/help/api/mcp>

## About

Connects an AI assistant to the Riddle creator API. You can list existing Riddles, build new quizzes, polls, forms and personality tests, edit them, and analyze results from a chat. Actions available through the Riddle API can be triggered through the assistant.

The server is hosted at https://www.riddle.com/creator/api/v3/mcp and uses streamable HTTP. A Riddle account is required. Users sign in with OAuth in the browser, and the token inherits that user's project roles and permissions. A key-in-URL option exists for headless agents, but OAuth is recommended.

## What it can do

- List existing Riddles in your account
- Build quizzes, polls, forms and personality tests
- Edit existing Riddles
- Analyze Riddle results and stats
- Sign in with your own Riddle account via OAuth

## Tools (48)

- `media_upload_link`: Creates a single-use link for uploading ONE media file into the media library.
- `media_delete`: Deletes a file from the media library permanently, to clean up after yourself: an upload that turned out wrong, or a file the user no longer wants stored (it frees the storage it counted against). (can modify or delete data)
- `riddle_template_create`: Stores an existing Riddle as a template of its project (or of the user, for a personal Riddle), so new Riddles can be created from it with riddle\_template\_use.
- `riddle_template_update`: Changes a template's title and/or its gallery image and icon. (can modify or delete data)
- `riddle_template_list`: Lists the templates of a project (or your personal ones) - the ones made from your own Riddles with riddle\_template\_create, NOT Riddle's public ones, which riddle\_template\_public\_list returns. (read-only)
- `riddle_template_public_list`: Lists Riddle's public templates - the ready-made ones every account has, as opposed to riddle\_template\_list's own ones. (read-only)
- `riddle_template_get`: Reads one template, by default INCLUDING its build configuration - the same "build" shape riddle\_get returns and riddle\_builder\_create accepts. (read-only)
- `riddle_template_use`: Creates a new Riddle from a template as an unchanged copy of it - content, settings and design preset - recorded as a copy of the template's Riddle (riddle\_get reports it as context.duplicated).
- `riddle_tag_list`: Lists the tags of a project as {items: \[{id, name, count, bankCount}\]}, unpaginated - the labels the Creator shows and riddle\_list's "tags" filter selects by, and where the ids that filter takes come from. (read-only)
- `riddle_tag_add`: Puts a tag on Riddles - ONE assignment per Riddle, never the tag itself (riddle\_tag\_list reads the labels of a project, riddle\_tag\_remove takes a tag off again, riddle\_tag\_delete removes a label).
- `riddle_tag_remove`: Takes a tag off Riddles - ONE assignment per Riddle (riddle\_tag\_add puts it on, riddle\_tag\_delete removes a label nothing carries). (can modify or delete data)
- `riddle_tag_delete`: Deletes the TAG ITSELF from a project - the label, for good - and no Riddle, no question bank and no assignment. (can modify or delete data)
- `ping`: A simple tool that returns "Pong". (read-only)
- `riddle_list`: Returns a paginated list of Riddles. (read-only)
- `riddle_get`: Reads one Riddle - or several, with UUIDs - as the compact build-configuration envelope {uuid, type, modifiedAt, build, nextBlockId, warnings, published, context}. (read-only)
- `riddle_get_embed_code`: Gets the HTML embed code for a Riddle by its UUID. (read-only)
- `riddle_publish`: Publishes one or many Riddles, or takes them off the web again with publish: false (there is no unpublish tool). (can modify or delete data)
- `riddle_rename`: Renames a Riddle with the specified UUID. (can modify or delete data)
- `riddle_delete`: Deletes one or many Riddles. (can modify or delete data)
- `riddle_move`: Moves one or many Riddles into another project or into the personal project - and, given no destination, reports whether it could instead of moving anything. (can modify or delete data)
- `whoami`: Reports the current API key: the authenticated user ("userEmail"/"userName", the latter null if never set), the project/team on a project-scoped key, whether this key has full access ("allowsFullAccess", see… (read-only)
- `question_bank_create`: Creates a new, empty question bank for the given Riddle type ("Quiz" or "Poll").
- `question_bank_list`: Lists question banks. (read-only)
- `question_bank_get`: Retrieves one question bank by id: title, riddleType, tags, notes, its categories/blockTypes and whether it has unpublished changes. (read-only)
- `question_bank_rename`: Sets the title of a question bank. (can modify or delete data)
- `question_bank_update_notes`: Replaces the plain-text maintainer notes of a question bank (never shown to participants) - the previous notes are overwritten entirely, not appended to, so read them with question\_bank\_get first and send everything… (can modify or delete data)
- `question_bank_duplicate`: Copies a question bank and all of its items into a new, independent bank (editing one never affects the other) in projectId or the key's project.
- `question_bank_publish`: Makes every item's draft content its published content - what a QuestionBank block of a live Riddle actually draws at view time - so the change reaches participants immediately: every Riddle using the bank is… (can modify or delete data)
- `question_bank_item_add`: Adds ONE new question/item to a question bank; nothing existing is changed (question\_bank\_item\_update replaces an item, question\_bank\_item\_delete removes one).
- `question_bank_item_update`: Replaces the content of ONE existing question/item of a question bank entirely - not a merge: blockType, category, difficulty and columns must all be sent even when unchanged, and a column or value left out is gone… (can modify or delete data)
- `question_bank_discard_changes`: Throws away every unpublished change to a question bank's items at once, resetting each of them to its last published content. (can modify or delete data)
- `question_bank_delete`: Deletes a question bank and every item it holds (its tags cleaned up exactly as question\_bank\_tag\_remove does) - one item alone is question\_bank\_item\_delete. (can modify or delete data)
- `question_bank_item_delete`: Deletes ONE question/item of a question bank and touches nothing else. (can modify or delete data)
- `question_bank_get_items`: Lists the items of a question bank - its DRAFT content by default, or its published items with published: true. (read-only)
- `question_bank_tag_add`: Adds a tag to a question bank, by tagName or tagId from riddle\_tag\_list - exactly one of the two, as riddle\_tag\_add does.
- `question_bank_tag_remove`: Removes a tag from a question bank, by tagName or tagId from riddle\_tag\_list - exactly one of the two. (can modify or delete data)
- `palette_get`: Reads the palettes - colors, fonts, button styles, background settings - of a Riddle: every palette it can use (the ones inherited from the account/project default preset included) with all of their values, which one… (read-only)
- `palette_customize`: Changes the palette (colors, fonts, button styles, background) of ONE Riddle, as a path =\> value map, e.g. (can modify or delete data)
- `integration_list`: Lists the Google Sheets and webhook integrations of a project as {items: \[{id, type, name, connectedRiddles}\]}. (read-only)
- `riddle_builder_create`: Builds a new Riddle of any of the nine types from a build configuration: "type" says which kind (see that argument for what each one is and what it needs at a minimum), "build" carries the content.
- `riddle_builder_update`: Edits an existing Riddle of any type with the same build configuration riddle\_builder\_create takes - but as a merge, not a rebuild: only the fields you send are touched, an omitted one is left exactly as it is. (can modify or delete data)
- `riddle_builder_validate`: Dry-runs one or many Riddle Builder creates and/or edits without creating or changing anything: per entry of "builds", the same validation the real call would apply, run against a scratch/deep-copied Riddle that is… (read-only)
- `reference_get`: Read this server's own documentation: the block types, form field types, result blocks, palette values and response shapes the other tools expect. (read-only)
- `stats_fetch`: Views/starts/submissions of one entity - "namespace" plus "entityId" says which (a project, a user, or a Riddle by UUID), "view" how deeply. (read-only)
- `project_list`: Lists the projects this token has access to as {items, page, pageSize, total, hasMore} - the paging every listing of this server answers with (riddle://reference/concepts/response-envelope), here 25 per page, 100 max… (read-only)
- `project_get`: Returns one project by id - id, name, image and the authenticated user's permission matrix for it. (read-only)
- `project_get_settings`: Returns the default Riddle settings every new Riddle of the project starts from - PUBLISHED and ENABLED only: "publishSettings" (privacy/DOI/OTP, email automation, tracking, data layer, ...) and "embedSettings" (iframe… (read-only)
- `riddle_preview`: Shows the user the current DRAFT of a Riddle as a playable preview - the Riddle as it looks right now, published or not. (read-only)

## Example prompts

- "List my most recent Riddles."
- "Create a five-question quiz about European capitals."
- "Build a personality test with three result pages."
- "Show the stats for my latest poll."

## Install

### Claude Code

1. Run this in a terminal, in your project folder:

```bash
claude mcp add --transport http riddle https://www.riddle.com/creator/api/v3/mcp
```

2. Start Claude Code, type `/mcp`, pick **riddle** and choose **Authenticate**. A browser window opens for the Riddle sign-in.

Add `--scope user` to make it available in every project, not just this one.

### Claude Desktop

1. Open **Customize → Connectors**, click **+ Add**, then **Add custom connector**.

2. Name it **Riddle** and paste this URL:

```url
https://www.riddle.com/creator/api/v3/mcp
```

3. Click **Add**, then **Connect**, and sign in when Riddle asks.

Claude Desktop’s JSON config file only starts local servers. Remote servers go through Connectors, and connectors you add on claude.ai show up here too.

### claude.ai

1. Open the connector form on claude.ai. This button fills in the name and URL for you:

[Add to claude.ai](<https://claude.ai/customize/connectors?modal=add-custom-connector&connectorName=Riddle&connectorUrl=https%3A%2F%2Fwww.riddle.com%2Fcreator%2Fapi%2Fv3%2Fmcp>) (opens connector settings)

2. Check that the URL reads `https://www.riddle.com/creator/api/v3/mcp` and click **Add**.

3. Click **Connect** and sign in when Riddle asks.

Free plans allow one custom connector. On Team and Enterprise plans an owner adds it under **Organization settings → Connectors**.

### ChatGPT

1. On chatgpt.com, go to **Plugins**, select **+**, then **Add custom MCP server**.

2. Enter a name for the server.

3. Under **Connection**, paste `https://www.riddle.com/creator/api/v3/mcp` as the server URL, then for authentication choose **OAuth**. ChatGPT sends you to Riddle to sign in.

4. Check **I understand and want to continue**, then select **Create as a plugin**.

Whether you can add a custom MCP server depends on your ChatGPT plan and your workspace permissions (in Business workspaces, admins and owners can).

### Cursor

[Add to Cursor](<https://cursor.com/install-mcp?name=riddle&config=eyJ1cmwiOiJodHRwczovL3d3dy5yaWRkbGUuY29tL2NyZWF0b3IvYXBpL3YzL21jcCJ9>) (opens Cursor)

Or add it by hand to `~/.cursor/mcp.json` (all projects) or `.cursor/mcp.json` (this project):

`mcp.json`:

```json
{
  "mcpServers": {
    "riddle": {
      "url": "https://www.riddle.com/creator/api/v3/mcp"
    }
  }
}
```

Cursor shows **Needs authentication** next to the server. Click the button beside it to sign in.

### VS Code

[Install in VS Code](<https://vscode.dev/redirect/mcp/install?name=riddle&config=%7B%22type%22%3A%22http%22%2C%22url%22%3A%22https%3A%2F%2Fwww.riddle.com%2Fcreator%2Fapi%2Fv3%2Fmcp%22%7D>) (opens VS Code)

Or from a terminal:

```bash
code --add-mcp '{"name":"riddle","type":"http","url":"https://www.riddle.com/creator/api/v3/mcp"}'
```

Or commit it to the repo in `.vscode/mcp.json`:

`.vscode/mcp.json`:

```json
{
  "servers": {
    "riddle": {
      "type": "http",
      "url": "https://www.riddle.com/creator/api/v3/mcp"
    }
  }
}
```

VS Code asks you to sign in the first time the server starts.

### Devin Desktop

1. Add it to `~/.config/devin/mcp_config.json` (macOS and Linux) or `%APPDATA%\devin\mcp_config.json` (Windows):

`mcp_config.json`:

```json
{
  "mcpServers": {
    "riddle": {
      "serverUrl": "https://www.riddle.com/creator/api/v3/mcp"
    }
  }
}
```

2. Refresh the MCP server list in Cascade and sign in when asked.

Devin Desktop is the new name for Windsurf. It reads `serverUrl` (or `url`) for remote servers.

### Codex

```bash
codex mcp add riddle --url https://www.riddle.com/creator/api/v3/mcp
codex mcp login riddle
```

Or edit `~/.codex/config.toml` directly:

`config.toml`:

```toml
[mcp_servers.riddle]
url = "https://www.riddle.com/creator/api/v3/mcp"
```

### Gemini CLI

```bash
gemini mcp add --transport http riddle https://www.riddle.com/creator/api/v3/mcp
```

Then, inside Gemini CLI, run `/mcp auth riddle` to sign in.

This adds it to the current project. Add `-s user` to use it everywhere.

### Any client

Most clients accept this shape. Some name the URL field differently: `serverUrl` in Devin Desktop, `httpUrl` in Gemini CLI’s settings file.

```json
{
  "mcpServers": {
    "riddle": {
      "type": "http",
      "url": "https://www.riddle.com/creator/api/v3/mcp"
    }
  }
}
```

Zed puts servers under `context_servers` in its settings. Cline needs `"type": "streamableHttp"`, or it assumes SSE.

Client only starts local servers? Bridge it with `npx -y mcp-remote https://www.riddle.com/creator/api/v3/mcp`.

## Recent changes

- 2026-11-11 14:54 UTC: 2 tools changed. Source: automatic check. Changed: riddle\_builder\_create, riddle\_builder\_update.
- 2026-11-11 11:47 UTC: 2 tools changed. Source: automatic check. Changed: riddle\_builder\_create, riddle\_builder\_update.
- 2026-11-02 11:51 UTC: 2 tools changed. Source: automatic check. Changed: riddle\_builder\_create, riddle\_builder\_update.
- 2026-10-30 11:46 UTC: 17 tools changed. Source: automatic check. Worth a look: a tool lost its read-only hint or gained a destructive one. Changed: integration\_list, media\_delete, media\_upload\_link, palette\_customize, question\_bank\_discard\_changes, question\_bank\_item\_update, question\_bank\_publish, question\_bank\_rename, question\_bank\_update\_notes, riddle\_delete, riddle\_get\_embed\_code, riddle\_preview, riddle\_rename, riddle\_template\_create, riddle\_template\_update, riddle\_template\_use, stats\_fetch.
- 2026-10-29 17:47 UTC: 11 tools added, 4 tools removed and 14 tools changed. Source: automatic check. Worth a look: a tool lost its read-only hint or gained a destructive one and a new tool is marked destructive. Added: question\_bank\_duplicate, question\_bank\_item\_add, question\_bank\_item\_delete, question\_bank\_item\_update, question\_bank\_publish, question\_bank\_rename, question\_bank\_tag\_add, question\_bank\_tag\_remove, question\_bank\_update\_notes, riddle\_tag\_add, riddle\_tag\_remove. Removed: question\_bank\_item, question\_bank\_manage, question\_bank\_tag, riddle\_tag. Changed: ping, question\_bank\_create, question\_bank\_delete, question\_bank\_discard\_changes, question\_bank\_get, question\_bank\_list, reference\_get, riddle\_builder\_create, riddle\_builder\_update, riddle\_builder\_validate, riddle\_move, riddle\_rename, riddle\_tag\_delete, riddle\_tag\_list.

More on the History tab, with descriptions before and after for the newest entries: https://mcp.tc/i/riddle#history (Atom feed: https://mcp.tc/i/riddle/history.xml). It records what mcp.tc's anonymous checks saw, every 3 hours where the tool list can be read without sign-in; it is not a security review.

## Details

- Server version: 1.0
- MCP protocol version: 2025-06-18
- Last checked: 2026-11-17 (reachable, asks for credentials)
- Listed: 2026-10-07
- Updated: 2026-10-30

---
Source: https://mcp.tc/i/riddle (mcp.tc is an independent directory, not affiliated with this server's publisher). Corrections: https://mcp.tc/report
