Docs · MCP · Claude Code
Connect HippoKit to Claude Code (MCP)
Claude Code is Anthropic's terminal coding agent, and it speaks MCP natively: you register HippoKit once with a single `claude mcp add` command and every Claude Code session can call it. This guide walks you through the connect flow, troubleshoots common issues, and answers the questions you'll have once HippoKit is live in Claude Code.
Claude Code is Anthropic's terminal coding agent, and it speaks MCP natively: you register HippoKit once with a single `claude mcp add` command and every Claude Code session can call it. It's a natural fit for engineers who want to turn the framework, API, or concept they just worked with into flashcards, a quiz, or an audience-themed slide deck without leaving the terminal.
What you can do once connected
Once Claude Code can call HippoKit, you can ask it to:
- Generate a study kit from any topic — flashcards, quiz, ebook, audience-themed slide deck, or AI-narrated audio. Each format obeys your HippoKit plan's quotas and feature gating.
- List or search your library — the host can look up kits you've already generated and pull them into the conversation by topic, audience, or recency.
- Run a review session — call
get_due_cardsandreview_cardto walk through the flashcards your spaced-repetition queue has surfaced for today. - Run a quiz — call
start_quizon any kit you own and answer each question conversationally. - Claim an anonymous preview — if a teammate sent you a preview kit URL, HippoKit can claim it into your library straight from the chat.
Connect HippoKit in 5 steps
Total time: about two minutes. You only need to do this once per device.
Generate a HippoKit personal access token (PAT)
Open https://hippokit.ai/settings/mcp while signed in to HippoKit. Click "Create token", name it (e.g. "Claude Code"), and copy the token — you only see it once. The token inherits your plan's quota and format gating.
Open your terminal where Claude Code is installed
Claude Code is the `claude` CLI. If you don't have it yet, install it first (`npm install -g @anthropic-ai/claude-code`). You register MCP servers with the `claude mcp` command — there is no settings GUI.
Add HippoKit with `claude mcp add`
Run: claude mcp add --transport http --scope user hippokit https://mcp.hippokit.ai/mcp --header "Authorization: Bearer <your PAT>". Replace <your PAT> with the token from step 1. The URL must end in /mcp — the bare host returns a misleading "authorization failed" error. `--scope user` makes HippoKit available in every project; drop it to scope the server to the current project only.
Verify HippoKit is connected
Run `claude mcp list` in your terminal — you should see `hippokit` listed. Inside a Claude Code session you can also run the `/mcp` command to see the server status and the nine tools it exposes.
Test it
Start a Claude Code session and ask: "Generate flashcards on photosynthesis using HippoKit". Claude Code should call HippoKit's `generate_kit` tool and return a shareable kit URL. If you see the kit, the connection is wired up correctly.
Quick reference
MCP server URL
https://mcp.hippokit.ai/mcpWhere PATs live
hippokit.ai/settings/mcpSettings location
your terminal (the `claude mcp add` command)
Smoke-test prompt
“Generate flashcards on photosynthesis using HippoKit”
60-second video walkthrough
A short screencast of the Claude Code connect flow is coming soon. For now, the five steps above are everything you need.
Troubleshooting
If something isn't working, walk this list top to bottom — common issues are listed first.
The host says HippoKit is unreachable or returns a 401.
Your PAT may have been revoked or rotated. Open https://hippokit.ai/settings/mcp, revoke any stale tokens, generate a fresh one, and update the host's saved credential.
The host refuses to call HippoKit tools mid-conversation.
Most hosts ask the user to approve each tool the first time it runs. Look for an inline approval prompt in the conversation transcript — sometimes it lives below the input box rather than inline with the assistant turn.
You hit a daily quota error.
MCP usage draws from the same monthly credit pool as the web app — Free is 60 credits/mo, Plus 150, Premium 500. See /pricing for the current numbers, or upgrade from /settings.
A specific format (e.g. audio) is rejected with an "unavailable" message.
Format gating mirrors the web app. Audio requires Plus or higher; the full 5-format kit requires Plus. Upgrade from /pricing or call `generate_kit` with a subset of formats your tier supports.
`claude mcp add` succeeds but `claude mcp list` shows HippoKit as failed or the tools never appear.
Confirm the URL ends in /mcp (not the bare host https:/.hippokit.ai/mcp), and that the header is exactly `Authorization: Bearer <your PAT>` with a real `hk_…` token. Re-add with the corrected value (`claude mcp remove hippokit` first), then restart the session so Claude Code re-reads its server list.
HippoKit shows up in one project but not another.
You probably added it at `--scope local` (the default — current project only). Re-add with `--scope user` to make HippoKit available across every project, or `--scope project` to share it with collaborators via a checked-in `.mcp.json`.
FAQ
Is HippoKit's MCP server free to use?
Yes — MCP usage is included in every HippoKit plan, including Free. There is no separate "API" tier. MCP calls draw from the same monthly credit pool you see in the web app, so a flashcard set generated through Claude Desktop costs you the same as one generated on hippokit.ai.
What can HippoKit do once connected?
The MCP server exposes nine tools: generate_kit, list_my_kits, get_kit, search_public_kits, claim_preview_kit, get_due_cards, review_card, start_quiz, and answer_quiz_question. Hosts can use these to generate new study content, list your existing library, look up specific kits, browse the public gallery, and run review sessions over your flashcard decks and quizzes.
Can I revoke access?
Yes — revoke any time from https://hippokit.ai/settings/mcp. Revocation is immediate; the host's next request gets a 401 and you can re-issue a fresh token whenever you want.
Can I use an environment variable instead of pasting my PAT into the host?
Yes, if your host supports bearer-token environment variables. For example, Codex Desktop's Streamable HTTP form can use `MCP_BEARER_TOKEN` in the "Bearer token env var" field. Set it on macOS with `launchctl setenv MCP_BEARER_TOKEN "hk_your_token_here"`, fully quit and reopen the app, then keep the headers section empty. If the host cannot read that environment variable, add an explicit header instead: `Authorization: Bearer <your PAT>`.
Does HippoKit see my host conversations?
No. The host only sends HippoKit the structured arguments for the tool calls it makes (e.g. "topic: photosynthesis, formats: flashcards"). The rest of your conversation stays inside the host. We never receive transcripts of your prompts to Claude / ChatGPT / Gemini / Cursor.
What's the difference between connecting Claude Code and Claude Desktop?
Same MCP server, different host. Claude Desktop is the GUI app and uses a Settings → Connectors screen with a browser authorize flow; Claude Code is the terminal CLI and registers HippoKit with the `claude mcp add` command plus a bearer-token header. Pick whichever you actually work in — you can connect both with separate PATs.
Does Claude Code send HippoKit my source code?
No. Claude Code only sends HippoKit the structured arguments for the tool calls it makes (e.g. "topic: React hooks, formats: flashcards"). Your files stay on your machine and inside Claude Code's own model context — HippoKit never receives code.
Connecting a different host?
HippoKit's MCP server works the same way across every host. Pick yours from the apex docs page.
All MCP hostsLast reviewed . Found something out of date? Email hello@hippokit.ai and we'll fix it.