Skip to main content
PricingBlogFree Tools
Developer docs

MCP server

Connect an AI assistant to your workspace

Flipbooker ships a Model Context Protocol server that exposes 50 tools. Point Claude, ChatGPT or any MCP-compatible client at it and your assistant can create flipbooks, manage subscribers and answer questions about reader analytics — no integration code.

Server endpoint

https://app.flipbooker.com/mcp/public-api

Connect a clientBrowse tools
claude_desktop_config.json
{
  "mcpServers": {
    "flipbooker": {
      "command": "npx",
      "args": [
        "-y", "mcp-remote",
        "https://app.flipbooker.com/mcp/public-api",
        "--header", "Authorization: Bearer ${FLIPBOOKER_API_KEY}"
      ],
      "env": { "FLIPBOOKER_API_KEY": "wsk_live_..." }
    }
  }
}

MCP or the REST API?

Both reach the same workspace with the same credentials and the same scopes. They differ in who is making the call.

Use MCP when a model is driving

The assistant picks the tool and fills the arguments from a conversation. You are wiring up an agent, an internal Claude workspace, or a chat-based workflow — and you are not writing request code at all.

Use REST when your code is driving

You control the sequence, handle pagination and retries, and need every endpoint — including the ones MCP does not expose. Backend jobs, CRM syncs and CI belong here.

REST API reference
MCP covers a subset of the API
The server exposes 50 tools; the REST API has 57 endpoints. Most per-reader analytics, the export family and webhook subscription management are REST-only. If a tool does not exist for what you need, call the endpoint directly.

Connecting a client

The server authenticates exactly like the REST API — a workspace API key as a bearer token, or an OAuth access token. Scopes are enforced per tool call.

  1. 1

    Create a scoped API key

    In the app, open Account → API Keys and create a key. Grant only the scopes the assistant should be able to use.

    This matters more for MCP than for REST: a model decides which tool to call, so the key is your enforcement boundary. A read-only assistant should get read scopes and nothing else.

    Scopes the tools use
    analytics:read
books:read
books:write
brand:read
brand:write
catalogs:read
catalogs:write
exports:read
subscribers:read
subscribers:write
tracked-links:read
tracked-links:write
webhooks:read
webhooks:write
  2. 2

    Point your client at the server

    The server speaks MCP over HTTP at https://app.flipbooker.com/mcp/public-api. Clients that only speak stdio can bridge with mcp-remote, as in the config above.

    Send the key as Authorization: Bearer wsk_live_…. OAuth access tokens are accepted on the same endpoint.

    Verify the endpoint responds
    curl -X POST https://app.flipbooker.com/mcp/public-api \
  -H "Authorization: Bearer $FLIPBOOKER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'
  3. 3

    Confirm the tools are visible

    Restart the client and check that the Flipbooker tools appear. Start with health_check — it needs authentication but no scope, so it isolates connection problems from permission problems.

    If tools list but calls fail with a scope error, the key is connected but under-scoped; rotate it with the scopes you need.

    Ask the assistant
    // In Claude, once connected:
"Run a Flipbooker health check"
"List my flipbooks, newest first"
"How many people opened the Q3 Sales Deck?"

Available tools

50 tools, each enforcing the same scope as the endpoint it maps to. A call without the required scope is refused before it reaches your data.

Analytics

analytics_list_book_view_events
analytics:read

Retrieve analytics data (view events) for a flipbook.

→ GET /analytics/book-view-events

book_id*cursordatelimitsource_host
analytics_list_interaction_events
analytics:read

List individual reader interaction events for a flipbook (page segments, link clicks, downloads, form and checkout events), newest first with cursor pagination. Requires the Company plan.

→ GET /analytics/interaction-events

book_id*cursordateevent_typelimitpage_numbersession_idtracked_link_idviewer_id
analytics_list_readers
analytics:read

List per-reader engagement summaries for a flipbook, including sessions, time spent, distinct pages viewed, downloads and link clicks. Requires the Company plan.

→ GET /analytics/readers

book_id*cursordateinclude_anonymouslimitsession_idsorttracked_link_idviewer_id
analytics_list_reader_pages
analytics:read

List page-by-page engagement for a single reader or anonymous session of a flipbook, including active time and segment counts per page. Requires the Company plan.

→ GET /analytics/reader-pages

book_id*datepage_numbersession_idtracked_link_idviewer_id
analytics_list_reading_session_pages
analytics:read

List the per-page breakdown of a single reading session, identified by its view event, for one flipbook. Requires the Company plan.

→ GET /analytics/reading-session-pages

book_id*view_event_id*
analytics_list_page_performance
analytics:read

List aggregate performance metrics per page of a flipbook, including unique readers and average active time across all readers. Requires the Company plan.

→ GET /analytics/page-performance

book_id*datetracked_link_id
analytics_get_book_flow
analytics:read

Get the page-by-page reader flow for a flipbook, showing reach rate and drop-off from the first page plus download and link-click aggregates. Requires the Company plan.

→ GET /analytics/book-flow

book_id*datetracked_link_id
analytics_list_audit_log
analytics:read

List the audit log for a flipbook, combining access requests and decisions with reader actions such as downloads, link clicks and form submissions, newest first with cursor pagination. Requires the Company plan.

→ GET /analytics/audit-log

book_id*cursordateevent_typelimittracked_link_idviewer_id
analytics_get_reader_journey
analytics:read

Get one reader or anonymous session's journey across every flipbook in the workspace, with per-book visits, pages viewed, time spent and engagement scores. Requires the Company plan.

→ GET /analytics/reader-journey

datesession_idviewer_id

Batches

books_get_batch
books:read

Get an upload batch with its job progress counts and the books it created.

→ GET /batches/{batchId}

batch_id*

Books

books_list
books:read

List flipbooks in the workspace with optional filtering and pagination.

→ GET /books

cursorfieldsfilterincludeslimitsort
books_get
books:read

Get a single flipbook in the workspace by ID, including its settings and metadata.

→ GET /books/{book}

book_id*
books_get_active_upload_status
books:read

Get the status of the upload batch currently in flight for the workspace, returning state idle when nothing is uploading.

→ GET /books/uploads/status/active

books_get_upload_status
books:read

Get the conversion progress of a file upload batch returned by books_upload_pdfs, reporting states queued, processing, completed, failed, or cancelled.

→ GET /books/uploads/{batchId}/status

batch_id*
books_upload_pdfs
books:write

Upload PDF, Word, Excel, or PowerPoint files using base64 content to create new flipbooks. Files are validated against the workspace plan.

→ POST /books

auto_links_enabledfilesoriginal_filenamepdfsstatus
books_update_settings
books:write

Update flipbook settings like title, description, status, and display options.

→ PUT /books/{id}

allow_fullscreenanimation_typebackgroundbook_id*copyright_enableddescriptiondomains_enableddownloadable_pdfeod_enabledflip_soundimage_displaymobile_animation_typepublished_dateshare_social_mediaslugstatus*title
books_create_konva
books:write

Create a flipbook from Konva canvas data plus one base64 page image per canvas page (maximum 250 pages, 15MB per image). Publishing immediately is subject to the published-book limit of the workspace plan.

→ POST /books/konva

canvas*page_images*settingsstatusthumbnailtitle*
books_create_from_template
books:write

Create a draft flipbook from WordPress posts or WooCommerce products, optionally laid out with a catalog template. Use source wordpress with source_type posts, or source woocommerce with source_type products.

→ POST /books/create-from-template

content*metadatasource*source_type*template_id

Brand

brand_get
brand:read

Get the current brand settings for the workspace.

→ GET /brand

brand_create
brand:write

Create brand settings for the workspace.

→ POST /brand

about_brandcompany_name*contact_numberfacebookgoogle_analyticsinstagramlinkedinpinterestprimary_colorsecondary_colortertiary_colortwitterwebsite_urlyoutube
brand_update
brand:write

Update existing brand settings.

→ PUT /brand

about_brandcompany_name*contact_numberfacebookgoogle_analyticsid*instagramlinkedinpinterestprimary_colorsecondary_colortertiary_colortwitterwebsite_urlyoutube
brand_toggle_take_over_branding
brand:write

Toggle the "take over branding" setting.

→ POST /toggle-take-over-branding

Catalogs

catalogs_list
catalogs:read

List the product catalogs in the workspace, newest first, excluding archived catalogs.

→ GET /catalogs

cursorlimit
catalogs_get
catalogs:read

Get a single product catalog by ID, including its source, metadata and last sync status.

→ GET /catalogs/{catalog}

catalog_id*
catalogs_list_items
catalogs:read

List the product items stored in a catalog, newest first, with cursor pagination.

→ GET /catalogs/{catalog}/items

catalog_id*cursorlimit
catalogs_get_sync_job
catalogs:read

Get the status, item counts and per-item errors of a catalog sync job.

→ GET /catalogs/{catalog}/sync-jobs/{syncJob}

catalog_id*sync_job_id*
catalogs_list_templates
catalogs:read

List the shared product-catalog flipbook templates that can be used to render a catalog, and report the default template ID.

→ GET /templates

type
catalogs_create
catalogs:write

Create a product catalog in the workspace and return it with its initial sync job; when external_id is supplied an existing catalog with the same source and external_id is updated instead. Metadata may only contain product data, not template or styling fields.

→ POST /catalogs

external_idmetadataname*sourcesource_url
catalogs_render
catalogs:read

Render the items of a product catalog into a new flipbook using a catalog template, either as a draft or published.

→ POST /catalogs/{catalog}/render

catalog_id*coveritemssettingsstatustemplate_idtitle
catalogs_bulk_upsert_items
catalogs:write

Create or update up to 500 product items in a catalog in one call, matching existing items on external_product_id and external_variant_id, and return the resulting sync job with per-item errors. Item payloads may only contain product data, not template or styling fields.

→ POST /catalogs/{catalog}/items:bulk-upsert

catalog_id*items*
catalogs_update_item_availability
catalogs:write

Apply an availability snapshot to up to 1000 existing catalog items, updating stock status and quantity, and return the resulting sync job with per-item errors. Items that do not already exist in the catalog are reported as errors.

→ PATCH /catalogs/{catalog}/items/availability

catalog_id*items*snapshot_at

Exports

exports_download_book_analytics_csv
exports:read

Export analytics data for a book as a CSV file.

→ GET /exports/analytics/{bookId}

book_id*dateoutput_object_keyoutput_pathsourcetracked_link_id
exports_download_book_leads_csv
exports:read

Export lead form submissions for a book as a CSV file.

→ GET /exports/books/{bookId}/leads

book_id*output_object_keyoutput_path
exports_download_book_interaction_events_csv
exports:read

Export the raw reader interaction events for a flipbook (page segments, link clicks, downloads, form and checkout events) as CSV. Requires the Company plan.

→ GET /exports/books/{id}/interaction-events

book_id*dateevent_typeoutput_object_keyoutput_pathpage_numbersession_idtracked_link_idviewer_id
exports_download_book_readers_csv
exports:read

Export one summary row per reader of a flipbook, aggregating their interaction activity, as CSV. Requires the Company plan.

→ GET /exports/books/{id}/readers

book_id*dateoutput_object_keyoutput_pathtracked_link_idviewer_id
exports_download_book_reader_pages_csv
exports:read

Export one summary row per reader and page of a flipbook, showing how each reader engaged with each page, as CSV. Requires the Company plan.

→ GET /exports/books/{id}/reader-pages

book_id*dateoutput_object_keyoutput_pathpage_numbertracked_link_idviewer_id
exports_download_book_page_performance_csv
exports:read

Export one summary row per page of a flipbook, aggregating reader engagement across all readers, as CSV. Requires the Company plan.

→ GET /exports/books/{id}/page-performance

book_id*dateoutput_object_keyoutput_pathtracked_link_idviewer_id
exports_download_book_audit_log_csv
exports:read

Export the combined audit log for a flipbook (access requests and decisions plus reader link, download, form and checkout events) as CSV. Requires the Company plan.

→ GET /exports/books/{id}/audit-log

book_id*dateevent_typeoutput_object_keyoutput_pathtracked_link_idviewer_id
exports_download_book_access_audit_csv
exports:read

Export the access audit trail for a flipbook, listing who requested access and whether it was granted or rejected, as CSV. Requires the Company plan.

→ GET /exports/books/{bookId}/access-audit

book_id*output_object_keyoutput_pathtracked_link_id

General

health_check
no scope required

Check the health status of the API. Authentication required, no scope required.

Subscribers

subscribers_list
subscribers:read

List all subscribers in the workspace with optional filtering.

→ GET /subscribers

filterpageper_pagetype
subscribers_create
subscribers:write

Add a new subscriber to a flipbook.

→ POST /subscribers

book_id*email*type

Tracked links

books_list_tracked_links
tracked-links:read

List all tracked links belonging to a book, including their slugs and share channels.

→ GET /books/{book}/tracked-links

book_id*
tracked_links_create
tracked-links:write

Create a new tracked link for click analytics.

→ POST /books/{book}/tracked-links

book_id*channelkindmetadataname*slug

Webhooks

webhooks_list_subscriptions
webhooks:read

List every analytics webhook subscription in the workspace, newest first, with its provider, target URL, subscribed event types, filters and delivery count.

→ GET /webhook-subscriptions

webhooks_list_subscription_deliveries
webhooks:read

List recent delivery attempts for a webhook subscription, newest first, including status, attempt count, response status, response body and error message.

→ GET /webhook-subscriptions/{subscription}/deliveries

limitsubscription_id*
webhooks_create_subscription
webhooks:write

Create an analytics webhook subscription that posts the selected reader events to an external URL.

→ POST /webhook-subscriptions

event_types*filtersis_activename*provider*signing_secrettarget_url*
webhooks_update_subscription
webhooks:write

Update an existing analytics webhook subscription; only the fields you provide are changed, and passing filters replaces the whole filter set.

→ PUT /webhook-subscriptions/{subscription}

event_typesfiltersis_activenameprovidersigning_secretsubscription_id*target_url
webhooks_test_subscription
webhooks:write

Queue a test delivery for a webhook subscription so a sample payload is sent to its target URL, and return the created delivery record.

→ POST /webhook-subscriptions/{subscription}/test

subscription_id*
webhooks_dispatch_sample
webhooks:write

Dispatch a sample webhook event for testing.

→ POST /webhooks

eventpayloadurl

* required argument.

Need something MCP does not expose?

The REST API covers the full surface — per-reader analytics, exports and webhook subscriptions included.

REST API referenceDeveloper guides