MCP Server

Deckbase MCP

Model Context Protocol server for Deckbase. AI tools (Cursor, Claude Code, VS Code, etc.) can read docs and manage decks and cards.

Endpoints

Mode	Endpoint	Auth
Hosted (HTTP)	POST /api/mcp	`Authorization: Bearer` — dashboard API key or OAuth access token. Same path in production: `/api/mcp`.

API keys are created in the dashboard. MCP is available for Pro and VIP subscribers. OAuth (browser login) is optional — see Connecting to Deckbase MCP and the full reference in docs/public/MCP.md via read_doc.

Tools

Documentation

Tool	Description	Parameters
list_docs	List Markdown files in `docs/public/`.	None.
read_doc	Read a doc by path. Only docs in `docs/public/` are served.	`path` — e.g. `MCP.md` or `deckbase://docs/public/MCP.md`.
list_template_block_types	Block type keys and numeric ids (text, media, quiz, layout). Use before `create_template`. Static data.	None.
list_block_schemas	JSON shapes per block type: `blocksSnapshot`, `values`, `configJson`. Pair with `export_deck` for real examples.	None.
list_elevenlabs_voices	ElevenLabs voice ids and labels for `voice_id` on `generate_audio_for_card`. Deckbase curated catalog. No user Firestore reads.	Optional `language`, `gender`, `search`.
list_ai_image_models	Allowed AI image model ids for `generate_image_for_card` with labels and credit costs.	None.

Decks & Cards — require API key

Tool	Description	Parameters
list_decks	User's decks (`deckId`, title, description, optional `defaultTemplateId`, optional `iconEmoji`).	None.
create_deck	Create a deck. Returns `deckId`, `icon_emoji` / `iconEmoji` when set.	`title` (required), `description` (optional), optional `icon_emoji` or `iconEmoji` (single emoji; AI clients should pick one that fits the title unless the user opts out).
update_deck	Update title, description, default template, or deck icon.	`deckId` (required); optional title, description, `default_template_id`, `icon_emoji` or `iconEmoji` (empty string clears the icon).
list_templates	Templates (`templateId`, name, description).	None.
get_template_schema	Exact JSON for the layout: `blockId`, type, `side` (`"front"` \| `"back"`), `configJson`, `valuesExample`, `create_card` hints.	`templateId` or `deckId` for the deck's default template.
create_card	New card from a template. Returns `cardId`, `templateId`, `usedDeckDefault`. `front` fills the main block; `block_text` keys include back-face blocks (`side` from `get_template_schema`).	`deckId` required. Optional `templateId`, `front`, `block_text`, `generate_audio`, `voice_id`, `audio_language`, `audio_gender`.
create_cards	Bulk create. Max 50 per request. On failure: `created` + `failedAt`.	`deckId`, `cards` array (required). Optional top-level `templateId`, `voice_id`, `generate_audio`.
update_card	Edit a card's content.	`deckId`, `cardId`; optional `values` / `blocks_snapshot`, or merge `front` / `block_text`.
delete_card	Soft-delete one card (trash). The server refuses unless `user_confirmed` is true — use only after explicit human consent.	`deckId`, `cardId`, `user_confirmed` (required boolean).
delete_cards	Bulk soft-delete in one deck. Same consent rule as `delete_card`. Max 50 per request.	`deckId`, `card_ids` (non-empty array), `user_confirmed`.
generate_audio_for_card	ElevenLabs TTS for an existing card.	`deckId`, `cardId`. Pass `voice_id` or `audio_language` + `audio_gender`. Optional `text`, `block_id`, `replace_existing`.
export_deck	Deck + cards JSON. Includes `truncated`, `exportType`. Full export includes per-card `blocksSnapshot` with `side` + `values`.	`deckId` (required); optional `max_cards` (default 2000, cap 5000), `export_type`: `full` or `values_only`.
create_template	New template (block layout). Returns `templateId` and block ids. Default Q+A if `block_types` omitted.	`name` (required); optional description, `block_types` / `blocks` (per-block `side`), `voice_id`, `audio_language`, `audio_gender`, `mainBlockId` / `subBlockId`.
update_template	Update metadata and/or layout. Bumps `version`.	`templateId` (required); optional name, description, `block_types` / `blocks`, `voice_id`, `audio_language` + `audio_gender`, `mainBlockId` / `subBlockId`.

Tools that read your data require a valid API key or OAuth token. list_template_block_types and list_block_schemas return static data (no auth needed). list_elevenlabs_voices doesn't read Firestore. Unauthenticated requests return 401.

Resources

The server exposes MCP resources for docs in docs/public/:

resources/list

One resource per .md file in docs/public/ (e.g. deckbase://docs/public/MCP.md).

resources/read

Fetch doc content by that URI.

Example: deck, template, and card

1
Configure your client with the MCP URL and Authorization: Bearer YOUR_API_KEY.
2
Call list_templates. If empty, use list_template_block_types and create_template first.
3
Call get_template_schema with the chosen templateId to learn exact blockId keys and side values.
4
Call create_deck with a title, optional description, and icon_emoji when the agent should pick a matching icon for the topic.
5
Call create_card with deckId and optionally templateId, front (main block), and block_text for other blocks including the back.

Technical details

ProtocolMCP 2024-11-05

Server namedeckbase-mcp

HostedJSON-RPC 2.0 over POST. Use a dashboard API key or OAuth access token (Bearer) — not a Firebase ID token.

Card shapecreate_card copies the template's block layout. Each block includes side from the template; empty values by default. Data is stored in Firestore and syncs to dashboard and mobile app.

For client setup (Cursor, VS Code, Claude, etc.), see Connecting to Deckbase MCP • For other links, see Resources