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 route stop needs narration audio, the tour needs a cover image, and non-flying tours need at least one route stop; audio is optional for points of interest) — otherwise it is saved as a draft and publishBlockers lists what's missing. A media URL that cannot be imported (rate limit, timeout, unsupported type) does not fail the call: the tour is created without it and mediaErrors lists each one (scope, storyIndex, field, url, error) so you can re-import it with import_media_url and attach it with update_tour/update_story or attach_media_to_*. Any other failure rolls the whole bundle back so nothing is saved, and it is safe to send again — do not resend a bundle that succeeded. 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 to a tour: route stops auto-play as travelers arrive; points of interest (role "poi") appear on the map and are played manually. Takes location, trigger radius (route stops only), text, narration script, media from URLs, and tags. New stories are appended to the tour unless orderIndex says otherwise. A media URL that cannot be imported (rate limit, timeout, unsupported type) does not fail the call: the story is created without it and mediaErrors lists each one (scope, field, galleryIndex, url, error) so you can re-import it with import_media_url and attach it with update_story or attach_media_to_story — do not resend a create_story that succeeded, or the tour gets a second copy of the story.
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 — route stops in listening order first, then points of interest (map-shown, played manually) — 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. Route stops keep the relative order you pass; points of interest always seat after the route stops (they never auto-play and have no place on the walked route).
set_story_role	Mark a story, within one tour, as a route stop (auto-plays as travelers arrive) or an off-path point of interest (shown on the map and played manually, never auto-triggered; with a category like viewpoint/restaurant/trailhead).
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