For developers & AI tools

Let your AI build History Cake tours.

Connect Claude, Cursor, or any MCP client to History Cake with an API key. Your assistant turns a researched document into a real tour — stories, locations, media, tags — and publishes it when it's ready.

Step 1

Get an API key

1
Sign in to Studio with a creator or admin account.
2
Open Settings → API tokens and create a token.
3
Copy it immediately — it's shown once. Tokens look like hc_mcp_…

Tokens are stored hashed, can expire, and can be revoked at any time. Your role is re-checked on every request.

Step 2

Connect your AI

Remote (recommended)

Point any client with remote MCP support straight at the hosted server:

claude mcp add --transport http history-cake https://historycake.app/api/mcp --header "Authorization: Bearer hc_mcp_..."

Via npx (stdio clients)

For clients that only speak stdio, the @history-cake/mcp bridge proxies to the same server:

{
  "mcpServers": {
    "history-cake": {
      "command": "npx",
      "args": ["-y", "@history-cake/mcp"],
      "env": { "HISTORY_CAKE_API_KEY": "hc_mcp_..." }
    }
  }
}

Step 3

From document to published tour

Create the tour in one call

create_tour_bundle takes the whole thing: tour fields, stories with coordinates and narration scripts, tags, and media imported from HTTPS URLs.

Add the media

import_media_url pulls images and audio into the media library; update_tour and update_story set covers and narration. Audio must be an HTTPS file — the MCP has no AI generation, so narration comes from your side or gets uploaded later in Studio.

Check, then publish

check_tour_publishable lists exactly what's missing (narration, cover image, route stops). When it's clean, publish_tour puts the tour live at its public URL.

The toolkit

16 tools, everything a tour needs

Create, inspect, update, reorder, tag, attach media, validate, publish. The full reference with JSON schemas lives at /llms-full.txt — readable by your AI directly.

Tool	What it does
create_tour_bundle	Create a complete History Cake tour in one call: tour fields, stories (with locations, narration scripts, role/POI status), tags, and media imported from HTTPS URLs. Created as a draft unless status is 'published' AND the tour passes publish validation (every story needs narration audio, the tour needs a cover image, and non-flying tours need at least one route stop) — otherwise it is saved as a draft and publishBlockers lists what's missing. This is the fastest way to turn a researched text document into a tour.
import_media_url	Import a single HTTPS image, audio, or video URL into the History Cake media library (downloads to S3). Returns a mediaId you can set as a tour cover, story image, or narration audio via the update tools. Only public HTTPS URLs are allowed.
create_story	Add one story (a geo-triggered narration stop) to an existing tour: location, trigger radius, text, narration script, role (route stop or off-path point of interest), media from URLs, and tags.
update_tour	Patch fields on a tour you own: name, descriptions, navigation type, story order mode, duration estimate, primary media (by mediaId from import_media_url), and tags (replaces all tags when provided; tags are created by name as needed). The public URL slug never changes after creation.
update_story	Patch fields on a story you own: text, narration script (audioScript), location, trigger radius, dates, primary media (by mediaId), and tags (replaces all tags when provided).
get_tour	Fetch full detail for a tour you own: all fields, tags, every story (with order, role, and whether it has audio/image/script yet), plus publishReadiness telling you exactly what still blocks publishing.
get_my_tours	List tours owned by the authenticated token's user (admins see all): id, slug, status, story count, and public URL.
get_story	Fetch one story's complete content by id: full WYSIWYG `description` text, the private `audioScript` narration, short description, exact location and trigger radius, dates, resolved primary image/video/audio URLs, gallery items, tags, and every tour it belongs to (with its per-tour order and role). Use this to read or audit a story's existing wording before editing it with update_story — list_stories and get_tour only report whether content exists, not the text itself.
list_stories	List every story in a tour in listening order, with role (route/POI), location, short description, and whether each has narration audio, a primary image, or an audio script. Pass includeContent:true to also return each story's full description text and audioScript so you can audit a whole tour's writing in one call.
reorder_stories	Set the listening order of a tour's stories. Pass every story currently in the tour (use list_stories first) as an ordered array of storyIds.
set_story_role	Mark a story as a route stop or an off-path point of interest (with a category like viewpoint/restaurant/trailhead) within one tour.
remove_story_from_tour	Detach a story from a tour (the story itself is kept; it must remain in at least one tour).
attach_media_to_story	Attach an existing media item (mediaId) or import an HTTPS URL into a story's gallery, with optional caption and order.
attach_media_to_tour	Attach an existing media item (mediaId) or import an HTTPS URL into a tour's gallery, with optional caption, role, and order.
list_tags	Browse existing content tags (optionally filtered by search) so you can reuse them instead of creating near-duplicates.
check_tour_publishable	Dry-run the publish validation for a tour. Returns ok plus the exact blocking errors (e.g. STORY_NO_AUDIO, NO_PRIMARY_IMAGE) and non-blocking warnings, without changing anything.
publish_tour	Validate and publish a tour you own. Fails with the list of blocking reasons if the tour isn't complete (run check_tour_publishable first). On success the tour goes live at its public URL.

Full schemas: /llms-full.txt · npm package: @history-cake/mcp

Good to know

Limits & guarantees

Creator accounts only

API keys can only be created by creator and admin accounts, and only touch your own tours.

120 requests per minute

Per token. Bundles count as one request.

HTTPS media only

Media imports fetch public HTTPS URLs server-side and store them in our media library.

No AI features over MCP

Your AI does the writing and narration. The MCP stores and publishes content — Studio itself never generates content for you.

Create your API key in Studio settings

Tool

create_tour_bundle

import_media_url

create_story

update_tour

update_story

get_tour

get_my_tours

get_story

list_stories

reorder_stories

set_story_role

remove_story_from_tour

attach_media_to_story

attach_media_to_tour

list_tags

check_tour_publishable

publish_tour