Docs · MCP

Connect Acornonaut to your AI assistant

Use Claude Desktop, Cursor, Cline, or any MCP-compatible client to search your flashcards, review due cards, and manage playlists from a conversation.

MCP Streamable HTTP · OAuth 2.0 · 20 tools

Get started Tool reference

Quick Start

Add this snippet to your AI client's MCP config file. Authentication happens automatically via OAuth on first connection.

Minimal config (works with any MCP client)

{
  "mcpServers": {
    "acornonaut": {
      "url": "https://mcp.acornonaut.app/mcp"
    }
  }
}

No API key needed. Acornonaut MCP uses OAuth — your browser opens once to authenticate, then the token is reused. See the OAuth flow below.

Using Claude or ChatGPT? You don't need a config file there. See Acornonaut in ChatGPT and Claude.

Client Setup

Claude Desktop

Open or create your Claude Desktop config file and paste the snippet. Then restart Claude.

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json

01Open the config file at the path above
02Paste the JSON snippet (merge with existing mcpServers if present)
03Save the file and fully restart Claude Desktop
04Test by asking: "What Acornonaut tools are available?"

claude_desktop_config.json

{
  "mcpServers": {
    "acornonaut": {
      "url": "https://mcp.acornonaut.app/mcp"
    }
  }
}

Cursor

Add the snippet to your Cursor MCP config. Use the project-level file for per-project setup, or the global file for all projects.

Project-level: .cursor/mcp.json
Global: ~/.cursor/mcp.json

You can also go to Cursor Settings → MCP and click Add Server to paste the URL directly.

.cursor/mcp.json

{
  "mcpServers": {
    "acornonaut": {
      "url": "https://mcp.acornonaut.app/mcp"
    }
  }
}

Cline

In VSCode with the Cline extension, add the server under cline.mcpServers in your VSCode settings JSON.

Or open the Cline sidebar, click the MCP Servers tab, and add a new server with URL https://mcp.acornonaut.app/mcp.

VSCode settings.json

// In VSCode settings.json:
{
  "cline.mcpServers": {
    "acornonaut": {
      "url": "https://mcp.acornonaut.app/mcp",
      "transport": "streamable-http"
    }
  }
}

Continue

Add the server to your Continue config file at ~/.continue/config.json.

Restart VS Code or run Continue: Reload Config from the command palette after saving.

~/.continue/config.json

// In ~/.continue/config.json:
{
  "mcpServers": [
    {
      "name": "acornonaut",
      "url": "https://mcp.acornonaut.app/mcp",
      "transport": "streamable-http"
    }
  ]
}

OAuth Flow

No API key to copy or manage. Acornonaut uses OAuth 2.0 — authentication is automatic and happens only once.

01Browser opens automaticallyOn first connection, your AI client opens a browser window to acornonaut.app.
02Sign in or create an accountLog in with your existing Acornonaut account, or sign up for free.
03Grant MCP accessOne-time consent screen — approve the tools your AI client can use.
04Return to your AI clientThe token is saved. Future connections are instant — no browser popup needed.

Tool Reference

20 tools covering the full learning workflow. Ask your assistant in plain language; it picks the tool.

Playlists

6 tools

list_playlistsList all your playlists with status and progress
search_playlistsSearch playlists by name or topic
get_playlistGet a single playlist with videos and cards
create_playlistCreate a new playlist from a YouTube URL
update_playlistRename or update playlist settings
delete_playlistPermanently delete a playlist and its cards

Videos

3 tools

add_video_by_urlAdd a single YouTube video to a playlist
get_video_cardsGet all flashcards for a specific video
get_transcriptRetrieve the full transcript of a video

Cards

7 tools

list_cardsList paginated flashcards with filters
get_cardGet a single card by ID
create_cardCreate a custom flashcard manually
update_cardEdit a card's front, back, or metadata
delete_cardDelete a specific card
search_cardsFull-text search across all your cards
regenerate_cardsRe-generate AI cards for a video

Learning

3 tools

get_due_cardsGet cards due for spaced-repetition review
record_reviewSubmit a review result (again/hard/good/easy)
get_statsGet your learning stats and streaks

Export

1 tool

export_deckExport a playlist as Anki-compatible CSV or JSON

Troubleshooting

"MCP server not found" error: Double-check the server URL is exactly https://mcp.acornonaut.app/mcp — no trailing slash, no typos. Also ensure the config file is valid JSON (use a linter if needed).
"Authentication failed" or 401 error: Your OAuth token may have expired. Go to your Acornonaut dashboard, disconnect the app under Settings → Connected apps, then reconnect from your AI client to trigger a fresh OAuth flow.
"OAuth popup blocked" or browser doesn't open: Allow popups for acornonaut.app in your browser settings. On macOS, check System Settings → Privacy & Security if the browser itself is blocked from opening. Alternatively, copy the OAuth URL from your AI client's logs and open it manually.
Tools not showing in my AI client: After editing the config file, you must fully restart your AI client (not just reload). For Claude Desktop, quit completely and relaunch. For Cursor, restart the window. Then verify by asking your AI: "What MCP tools are available?"
Tools work but no cards are returned: You may be authenticated as a different account than the one with your playlists. Check which account you logged into during the OAuth flow. You can also run get_stats to see your account info.

Ready to connect?

Paste the config, restart your client, and ask it what's due today.

Open dashboard View plans