LearnReally
Docs — MCP

Your agent already taught you. Now it writes the cards.


The LearnReally MCP server is open source (MIT) and runs inside your own agent. As it teaches you — debugging, explaining, drilling — it calls the card-writing tools with real pedagogy enforced server-side, and the cards land on your phone. Free: the authoring work runs in your agent, not on our models.

Set up with your agent

Your agent will ask for an API key — mint one under Account API keys.

Set up the LearnReally MCP server for me.

WHAT IT IS: an open-source (MIT) MCP server published as the npm package @learnreally/mcp, run over stdio with npx. It adds three tools — create_deck, add_cards, list_decks — that write spaced-repetition cards to my LearnReally account.

1. THE KEY. The server authenticates with my personal API key, passed as the environment variable LEARNREALLY_API_KEY. Ask me for it and stop until I reply — never invent, guess, or reuse another key. If I don't have one, tell me to mint it at https://learnreally.com/settings (Account → API keys; it is shown once).

2. THE CONFIG. Work out which client you are running inside and register a stdio server named "learnreally" in that client's own format, passing my key as the LEARNREALLY_API_KEY environment variable (replace the placeholder in the sample). The shape most clients use:

{
  "mcpServers": {
    "learnreally": {
      "command": "npx",
      "args": ["-y", "@learnreally/mcp"],
      "env": {
        "LEARNREALLY_API_KEY": "lr_live_…your-key…",
        "LEARNREALLY_API_BASE_URL": "https://learnreally.com"
      }
    }
  }
}

The clients that differ:
- Claude Code — one command instead of a file:
claude mcp add --transport stdio learnreally \
  --env LEARNREALLY_API_KEY=lr_live_…your-key… \
  --env LEARNREALLY_API_BASE_URL=https://learnreally.com \
  -- npx -y @learnreally/mcp
- OpenAI Codex CLI — TOML at ~/.codex/config.toml: table [mcp_servers.learnreally] (snake_case) with a nested [mcp_servers.learnreally.env] table.
- Grok Build (xAI) — the same TOML, at ~/.grok/config.toml. Grok's in-app connectors take remote servers only, so a local one goes in the CLI.
- OpenCode — top-level "mcp", "type": "local", a single "command" array, and "environment" (not "env").
- OpenClaw — ~/.openclaw/openclaw.json, nested one level deeper: a "servers" map inside a top-level "mcp" object (not a root "mcpServers").
- Hermes (Nous Research) — YAML at ~/.hermes/config.yaml: top-level "mcp_servers", each server with command/args/env.
- VS Code (Copilot) — .vscode/mcp.json with the root key "servers" (not "mcpServers") and "type": "stdio".
- ChatGPT — not possible: it connects only to remote hosted MCP servers, never a local npx one.

3. VERIFY. Reload the client — usually I have to restart it myself, so tell me when — then call the list_decks tool. My decks (or "No decks yet") means it works. An authentication failure means the key; a startup failure means the command or LEARNREALLY_API_BASE_URL.

4. AFTER THAT. Tell me it is connected. From then on, whenever you teach me something I want to keep, call create_deck / add_cards and write active-recall cards for it — the server enforces the card rules and returns the reason for anything it rejects.
Before you start

Mint an API key.

The MCP authenticates with a personal key — create one under Account API keys (shown once; store it somewhere safe), then drop it into your client's config as LEARNREALLY_API_KEY. Revoke a key any time; the cards it wrote stay yours.

Connect your agent

The other path: add the open-source LearnReally MCP to your coding agent and it writes cards onto your account as it teaches you — no copy-paste. Mint a key above and drop it in as LEARNREALLY_API_KEY.

Works today — a local server

Every client here runs the server on your own machine, over stdio. Most share the one config below; the few that differ have their own block.

Default — Claude Desktop · Cursor · Windsurf

{
  "mcpServers": {
    "learnreally": {
      "command": "npx",
      "args": ["-y", "@learnreally/mcp"],
      "env": {
        "LEARNREALLY_API_KEY": "lr_live_…your-key…",
        "LEARNREALLY_API_BASE_URL": "https://learnreally.com"
      }
    }
  }
}

Cursor reads this from ~/.cursor/mcp.json (or a project .cursor/mcp.json); Claude Desktop from its claude_desktop_config.json.

Claude Code

One command — or paste the default block into a project .mcp.json (add "type": "stdio"):

claude mcp add --transport stdio learnreally \
  --env LEARNREALLY_API_KEY=lr_live_…your-key… \
  --env LEARNREALLY_API_BASE_URL=https://learnreally.com \
  -- npx -y @learnreally/mcp
OpenAI Codex CLI

TOML, not JSON — the table is mcp_servers (snake_case) with a nested .env table. If it doesn't show up, update Codex.

# ~/.codex/config.toml
[mcp_servers.learnreally]
command = "npx"
args = ["-y", "@learnreally/mcp"]

[mcp_servers.learnreally.env]
LEARNREALLY_API_KEY = "lr_live_…your-key…"
LEARNREALLY_API_BASE_URL = "https://learnreally.com"
Grok Build (xAI)

The same TOML grammar as Codex, in its own file — ~/.grok/config.toml (a project .grok/config.toml works too).

# ~/.grok/config.toml
[mcp_servers.learnreally]
command = "npx"
args = ["-y", "@learnreally/mcp"]

[mcp_servers.learnreally.env]
LEARNREALLY_API_KEY = "lr_live_…your-key…"
LEARNREALLY_API_BASE_URL = "https://learnreally.com"
OpenCode

Its own shape: top-level mcp, a single command array, and environment (not env).

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "learnreally": {
      "type": "local",
      "command": ["npx", "-y", "@learnreally/mcp"],
      "enabled": true,
      "environment": {
        "LEARNREALLY_API_KEY": "lr_live_…your-key…",
        "LEARNREALLY_API_BASE_URL": "https://learnreally.com"
      }
    }
  }
}
OpenClaw

Nested one level deeper: servers lives inside a top-level mcp object in ~/.openclaw/openclaw.json, not at the root. openclaw mcp add writes the same entry from the shell.

{
  "mcp": {
    "servers": {
      "learnreally": {
        "command": "npx",
        "args": ["-y", "@learnreally/mcp"],
        "env": {
          "LEARNREALLY_API_KEY": "lr_live_…your-key…",
          "LEARNREALLY_API_BASE_URL": "https://learnreally.com"
        }
      }
    }
  }
}
Hermes (Nous Research)

YAML, not JSON — mcp_servers in ~/.hermes/config.yaml (or hermes mcp add from the shell). After an edit, /reload-mcp or a fresh session picks it up.

# ~/.hermes/config.yaml
mcp_servers:
  learnreally:
    command: "npx"
    args: ["-y", "@learnreally/mcp"]
    env:
      LEARNREALLY_API_KEY: "lr_live_…your-key…"
      LEARNREALLY_API_BASE_URL: "https://learnreally.com"
VS Code (Copilot)

Same fields, but the root key is servers — pasting a mcpServers block here is the #1 setup mistake.

// .vscode/mcp.json — note the key is "servers", not "mcpServers"
{
  "servers": {
    "learnreally": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@learnreally/mcp"],
      "env": {
        "LEARNREALLY_API_KEY": "lr_live_…your-key…",
        "LEARNREALLY_API_BASE_URL": "https://learnreally.com"
      }
    }
  }
}

Chat apps — hosted connectors only

ChatGPT and the Grok app take MCP servers as connectors, and a connector has to be a remote server their side can reach over the internet. Ours runs on your machine, so neither can see it today. A hosted LearnReally connector is on the roadmap — that is what will open these two. Until then, use one of the clients above, or just build a deck at the top of this page.

ChatGPT

Its connectors take a server URL over HTTPS — there is no field for a command, so a local npx server can't be registered at all.

Grok (app and bot)

xAI states the rule plainly: an MCP server “must be reachable over the public internet”. Grok Build — the CLI, listed above — is a different product and is unaffected: it starts the server on your own machine.

Good to know

What the tools enforce.

Every card an agent submits passes the server-side quality guard: active-recall phrasing, one idea per card, a reference answer the grader can actually judge against. Junk cards are rejected with the reason, so a sloppy prompt can't quietly fill your deck with noise. Cards can carry an image or audio when it genuinely adds a second information channel — the tool documentation your agent reads explains when (dual coding), and when not (decoration). Media is hotlinked by URL: prefer stable public sources (Wikimedia, official docs) — a dead link degrades the card to plain text.

The server is MIT-licensed and ships as @learnreally/mcp with its full source — read every line of what leaves your machine, fork it, or point it at your own backend.

Connect your agent (MCP) — LearnReally