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/v1/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 — Claude, Cursor, 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/v1/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/v1/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, so the linked reference is the source of truth for a tool's inputs. The set is intent-oriented rather than a 1:1 mirror of the REST API: closely related endpoints are merged into a single tool, and resources assistants rarely need (such as card layouts) are left out.

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.
`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.
`get_deck_progress`	The latest deck progress snapshot, or its 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.

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_card`	Update a card's content.
`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_card.

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