Connect Riddle to Claude (MCP)

Connect your Riddle account to Claude — or any other AI assistant that supports MCP (e.g. Cursor, Cline, ChatGPT) — and let it create, analyze, and manage your Riddles for you. Just ask in plain English, "Build me a 5-question quiz on solar panels in German", and the AI does it directly in your account.

This guide uses Claude in the examples, but the setup is similar for any MCP-compatible client.

What is MCP?

MCP stands for Model Context Protocol. It's an open standard that lets AI assistants connect to external tools — in this case, your Riddle account. Once connected, the AI can use the same actions you'd run manually: list, create, publish, get stats, generate Riddles with AI, and more.

The setup takes about 2 minutes. If you're a developer integrating MCP into your own client (e.g. with the Model Context Protocol Inspector or a custom agent), see the technical MCP guide instead — it lists all tools, resources, and authentication details.

Good to know before you start:

  • Mobile apps: Custom MCP connectors currently only work in Claude on web and desktop, not in the mobile apps.
  • Plans: Creating, publishing, and managing Riddles works on every plan. Stats tools (views, submissions, breakdowns) require a Business or Enterprise plan.
  • AI credits: AI generation tools (e.g. "Make me a quiz about X") consume your account's AI usage credits, just like generating Riddles in the Creator. Ask the AI "How much AI usage do I have left?" anytime to check your quota.

Step 1: Create an MCP key in Riddle

Go to your API/MCP keys page in the Riddle creator.

Riddle API/MCP keys page

Click on CREATE NEW MCP KEY. Make sure you click the MCP button — not "Create new API key". Regular API keys do not work with MCP and will return an authentication error.

Give your key a name (e.g. "Claude") and click CREATE.

Create new MCP key dialog

Copy the key shown to you — you'll need it in the next step. Treat it like a password: anyone with this key has full access to your Riddle account.

Don't see the MCP button? If you only see "Create new API key" and not the MCP option, your user role doesn't have MCP permissions. Ask your project admin to grant them or to create the key for you.

Step 2: Add Riddle as a custom connector in Claude

Open Claude, go to Settings → Connectors, and click on Add custom connector at the bottom of the page.

Claude Connectors settings page

Fill in the dialog:

  • Name: Riddle
  • Remote MCP server URL: https://www.riddle.com/creator/api/v3/mcp/YOURKEY

Replace YOURKEY with the MCP key you copied in Step 1.

Add custom connector dialog

Click Add. That's it — Claude is now connected to your Riddle account.

Step 3: Verify the connection and try it out

Open a new Claude conversation. Make sure the Riddle connector is toggled on for that conversation — you'll find it via the connector icon below the chat input. Then ask:

"Show me my last Riddle."

If Claude returns one of your Riddles, you're set. (If not, see Troubleshooting below.)

Now try anything you'd normally do in Riddle:

  • "List my last 5 Riddles."
  • "Create a quiz about climate change with 7 questions in English."
  • "Show me the stats for my 'Brand awareness quiz' from the last 30 days."
  • "Publish the Riddle named 'Holiday giveaway 2026'."

Claude will pick the right tool and carry out the action in your account.

Best practices: Get top results with fewer tokens

How you prompt directly affects speed, accuracy, and token cost. These five tips give you the biggest wins.

1. Be specific upfront

Instead of "Make a quiz about marketing", try:

"Create a 5-question quiz on email marketing best practices, in English, single-choice answers, with a results page that shows a score."

The more constraints you give in the first prompt, the fewer back-and-forth turns you need.

2. Provide IDs or filter the scope

Pass UUIDs, exact names, projects, types, or date ranges whenever you have them:

  • "Get the embed code for Riddle 1a2b3c4d-..." beats "Find the quiz I made about pets".
  • "Stats for the last 7 days in the 'Marketing' project" beats "All my stats".

This skips listing/searching steps and keeps responses small.

3. Pick the right kind of creation

Riddle's MCP can create content in two ways — and your phrasing tells the AI which to use:

  • "Build a quiz with these exact 5 questions: …" → the AI uses the structured builder. Best when you already know your content.
  • "Make me a quiz about X" → the AI lets Riddle's AI generation invent the questions. Best for fast, topic-based content.

Match your prompt to your intent: builder for precision, generation for speed.

4. Set the context once

State recurring requirements at the start of a conversation, not in every prompt:

"For all Riddles in this conversation: friendly tone, address the user with 'you', language German."

The AI will apply this to every Riddle it creates afterwards.

5. Iterate, don't restart

If something's off, refine it: "Change question 3 to multiple-choice", "Translate the result page to French". Iterating on an existing Riddle is faster and cheaper than deleting and starting over.

Troubleshooting

"Authentication failed" Re-create the MCP key in Riddle and update the connector URL in Claude. Make sure it's an MCP key, not an API key.

"I don't have access to project X" The MCP key only works for projects where your user has the right AI permissions. Ask your project admin to grant access.

Claude doesn't seem to use the connector Check that the connector is enabled in your Claude conversation. Click the connector icon below the chat input and make sure "Riddle" is toggled on.

Key compromised? Revoke it. If you suspect your MCP key has been shared or leaked, go to your API/MCP keys page, click the trash icon next to the key, and the key is revoked instantly. Then create a new MCP key and update the connector URL in Claude.

Still stuck? Reach out to our support team via the support chat or via email.

Next steps

Table of Contents