Vocabit

What the Vocabit MCP server does

The Vocabit MCP server gives an AI assistant a complete study-set loop: generate cards, publish them to the Vocabit app, inspect what the learner studied, and revise the material afterward. A created set returns a deep link that can open the set on the learner’s device. The assistant can also attach a topic and notes to a set for later context.

Progress comes from Vocabit’s spaced-repetition engine rather than an assistant-generated estimate. Cards can be reported as new, struggling, learning, or mastered. A set becomes completed when no cards remain new. Study history remains available after a set is deleted.

How it works

The server exposes MCP tools over a stdio transport. In live mode, an HTTP client sends requests to a configured Vocabit backend and identifies itself with an agent key. In demo mode, an in-memory client provides the same tool surface with two seeded sets and a deterministic simulated learner, making it possible to test the workflow without an account or backend.

The usual loop starts with create_study_set, followed by learner activity in the Vocabit app. get_set_results then returns per-card statuses, weak cards, untouched cards, due cards, and review information. An assistant can use those results to call update_study_set, commonly by appending cards or changing the title or tags. The study-session prompt is available to guide the full sequence.

Setup and configuration

Run the published package with npx -y vocabit-mcp. With neither live connection variable set, the server starts in demo mode. To connect to a real backend, set both VOCABIT_BASE_URL and VOCABIT_AGENT_KEY; the key must match one of the backend’s configured agent API keys. Supplying only one of those values causes startup to fail rather than selecting a partial configuration.

Optional settings include the learner’s Firebase UID, default term and definition languages, a Telegram recipient, and an HTTP timeout. VOCABIT_DEMO=1 explicitly selects demo mode. The default request timeout is 20,000 milliseconds.

For inspection without a host application, run the server through the MCP Inspector in demo mode. Claude Code can add it with claude mcp add vocabit -- npx -y vocabit-mcp, while Claude Desktop and other MCP clients can use an equivalent stdio configuration.

Tools and capabilities

• vocabit_health reports connection status and the active mode.
• create_study_set publishes a set and returns its device deep link.
• list_study_sets returns recent sets with progress summaries.
• get_study_set retrieves a set’s cards, topic, and attached notes.
• get_set_results reports card-level outcomes, weak and untouched cards, due cards, and review data.
• update_study_set changes metadata or appends cards.
• notify_learner sends a Telegram notification that a set is available.
• delete_study_set removes a set while retaining its study history.

The vocabit://set/{setId} resource exposes a set as JSON, and the server includes a study-session prompt for the end-to-end workflow. Read-only tools are annotated as such, while deletion is marked as destructive.

Limitations and notes

The server depends on a Vocabit backend with its agent API enabled for live use. Multi-learner support without a backend default UID, streamable HTTP transport, and audio pronunciation cards are listed as roadmap items rather than current capabilities. Telegram notification contacts a real person, so notify_learner should be used deliberately. Demo learner activity is simulated and marked in responses; it should not be treated as real learner performance.