MCP server

Recall exposes a Model Context Protocol (MCP) server, so AI assistants can manage your decks and cards in natural language. It runs on the same infrastructure as the REST API, supports OAuth and API-key authentication, and exposes a curated set of high-level tools rather than the full REST surface.

Endpoint

https://api.recall.cards/mcp

The server speaks Streamable HTTP. Point any MCP client at this URL.

Authentication

The MCP server supports two ways to authenticate.

OAuth (recommended)

Most MCP clients like Claude or ChatGPT speak OAuth out of the box. Point the client at the endpoint with no credentials and it opens your browser so you can sign in to Recall and approve access. The client registers itself automatically (Dynamic Client Registration), so there is nothing to set up in advance, and Recall issues short-lived access tokens that refresh in the background.

Recall follows the MCP authorization spec: OAuth 2.1 with PKCE, Protected Resource Metadata for authorization-server discovery, and Dynamic Client Registration.

API key

For headless clients (CI jobs, scripts, servers) where a browser sign-in is impractical, authenticate with an API key as a Bearer token instead.

Authorization: Bearer YOUR_API_KEY

Requests without a valid access token or API key are rejected with a 401 Unauthorized.

Treat your API key like a password: anyone with it can read and modify your decks and cards. You can revoke and rotate keys anytime in your settings.

Connecting a client

Claude Code

With OAuth, add the server with just its URL, then approve access in your browser:

claude mcp add --transport http recall https://api.recall.cards/mcp

Run /mcp in a session: Claude Code opens a browser for you to sign in to Recall and approve access, then confirms the server is connected.

To use an API key instead — for example on a headless machine — pass it as a header:

claude mcp add --transport http recall https://api.recall.cards/mcp \
  --header "Authorization: Bearer YOUR_API_KEY"

Test it

Before wiring a client, you can smoke-test the server with the MCP Inspector:

npx @modelcontextprotocol/inspector

Choose Streamable HTTP, set the URL to the endpoint above, then connect. The Inspector walks you through the OAuth sign-in, or you can add an Authorization header with your API key instead.

Tools

The server exposes a focused set of high-level tools. Each one wraps a REST endpoint and inherits its validation, limits, and error behavior.

Decks

Tool	Description
`list_decks`	List your decks, most recent first, with their due cards counts.
`get_deck`	Retrieve a deck with its fields.
`create_deck`	Create a deck, optionally with its fields and their AI Autofill.
`copy_deck`	Copy a deck with its fields, layouts, and cards.
`update_deck`	Rename a deck or change its study settings.
`pause_deck`	Pause the study of a deck.
`unpause_deck`	Resume the study of a paused deck.
`schedule_deck_cards`	Schedule the deck's next batch of new cards for review now.
`get_deck_progress`	The latest deck progress snapshot.
`list_deck_progress`	The deck progress history over a date window.

Deck fields

Tool	Description
`add_deck_fields`	Add fields to an existing deck.
`update_deck_field`	Rename a field or change its AI Autofill configuration.
`generate_deck_field_values`	Generate a field's value on every card with AI Autofill.
`delete_deck_field`	Delete a field and its content on every card.

Card layouts

Tool	Description
`list_card_layouts`	List a deck's card layouts with their layout fields.
`create_card_layout`	Create a card layout, e.g. to test another direction of the same cards.
`update_card_layout`	Set or remove a card layout's review prompt.
`activate_card_layout`	Activate a layout so it is reviewed again.
`deactivate_card_layout`	Deactivate a layout, keeping its learning progress.
`set_primary_card_layout`	Make a layout the deck's primary card layout.
`delete_card_layout`	Delete a card layout and its variants' learning progress.
`add_card_layout_fields`	Display deck fields in a layout, as layout fields.
`update_card_layout_fields`	Restyle, reorder, or move one or more layout fields in a single call.
`remove_card_layout_field`	Remove a layout field from its layout.

Cards

Tool	Description
`add_cards`	Create up to 100 cards in a deck, with optional AI Autofill.
`list_cards`	List cards, optionally filtered to a single deck.
`get_card`	Retrieve a card with its card variants (scheduling state).
`update_cards`	Update the content of one or more cards in a single call.
`delete_cards`	Delete one or more cards and their review history.

Scheduling

Tool	Description
`list_card_variants`	List card variants, filterable by deck, card, stage, or difficulty.
`update_card_scheduling`	Apply a scheduling action to a variant: `schedule`, `snooze`, `suspend`, or `unsuspend`.
`list_card_reviews`	List the review history, filterable by deck, card, or variant.

Card content is keyed by each deck field's key, so an assistant should call get_deck (or read the response of create_deck) to learn the keys before calling add_cards or update_cards.

Errors

Tool calls surface the same error object as the REST API. When a call fails, the assistant receives its message, code, and param, so it can explain what went wrong and how to fix it.

Card reviews