Nado Language MCP

This MCP server lets AI chat clients save Nado Language reading articles and practice existing saved materials. Nado supports both a hosted remote MCP endpoint and a local stdio package.

Remote MCP endpoint:

https://ptbwzhxifxdnfmqsiugi.supabase.co/functions/v1/mcp

The remote endpoint uses MCP Streamable HTTP. Clients that support remote MCP can connect to that URL without installing the local package. Protected tools require an authenticated Nado Bearer token or equivalent account linking before saving or loading user data.

Tools

• nado_whoami: validates the configured Nado account.
• nado_update_study_item: updates an existing saved Nado card with a revised meaning, description/explanation, examples, variants, or context. It cannot create new cards.
• nado_save_article: free and unlimited. Saves a full article, passage, webpage excerpt, or reading material into Nado custom_articles, with an optional highlights row. It does not create flashcards.
• nado_list_study_items: loads saved flashcards for the authenticated user.
• nado_generate_practice: builds practice exercises from saved flashcards only.

MCP intentionally cannot create memorization cards. Nado's learning flow is to read saved material first, then create cards inside Nado from selected unknown words or phrases. Legacy direct calls to nado_save_flashcard, nado_save_study_item, or nado_analyze_and_save_flashcard return FLASHCARD_SAVE_DISABLED.

Intent routing:

• If the user asks to save a full article, passage, webpage excerpt, or reading material with phrases like "Nado 기사로 저장해줘", "아티클로 저장", "읽을 자료로 저장", or "save this as an article", use nado_save_article. This stores article/highlight rows, not flashcards.
• If the user provides a new English item and says "hi 를 단어장에 저장해줘", "나두 암기장", "nado 암기장", "암기할래", "외울래", "암기장에 추가", "단어장에 넣어줘", "remember this", or "add this to my flashcards", do not create a card through MCP. Ask the user to save the surrounding article/text with nado_save_article and create cards inside Nado while reading.
• If the user asks to add or change description/설명/뜻/예문 on an already saved card, use nado_update_study_item.
• If the user asks to study already saved cards with phrases like "암기장에 있는 단어로 작문연습하자", "저장된 단어로 작문연습", "외울래", "암기 연습", "퀴즈 내줘", "쓰기연습", "영작하기", or "복습할래", use nado_generate_practice. For 작문연습/쓰기연습/영작하기, set mode to writing.
• If the user wants to inspect saved items first, use nado_list_study_items.

Authentication

For most learners, install or update the package, sign in once, then restart the AI app and start a new chat:

npm install --global @nado-language/mcp@latest
nado-mcp login

Install on macOS with Homebrew:

brew install jintonyc/tap/nado-mcp

The npm install/update step auto-registers supported local AI apps when possible. nado-mcp setup ... and nado-mcp doctor are troubleshooting commands, not part of the normal learner flow.

If the browser login succeeds but the page cannot post back to the local helper, the page shows a manual fallback command:

nado-mcp login --code <manual-code-from-browser>

The manual code contains Nado session access. Do not share it.

Source checkout alias:

npm run mcp:nado:auth

This opens the Nado web connect page. The user signs in there with any login method already supported by Nado, then the page sends the browser session to the local 127.0.0.1 helper and writes ignored local tokens to the user's OS config directory for package installs or .env.mcp.local in a repo checkout:

NADO_MCP_ACCESS_TOKEN='supabase-user-access-token'
NADO_MCP_REFRESH_TOKEN='supabase-user-refresh-token'

By default this uses the existing Azure Static Web Apps production site as a provider-neutral connect page. It does not require a new Azure Function, App Service, database, or paid runtime. The browser posts the session directly to the local helper; tokens are not placed in the browser URL.

Legacy direct OAuth remains available with nado-mcp login --provider google|kakao|apple, but normal users should omit --provider.

The MCP server refreshes expired access tokens with NADO_MCP_REFRESH_TOKEN and updates the auth file when Supabase rotates the refresh token.

Supported web login methods are the same as Nado web login, including Google, Kakao, Naver, and Apple.

Legacy direct OAuth provider mode requires Supabase Auth to allow the Azure relay redirect URL:

https://language.nado.ai.kr/auth/mcp-callback

Register the exact URL above. Do not include local_callback, provider, or other query parameters in the Supabase allow list.

For direct local callback mode, run with --redirect-mode local and allow:

http://127.0.0.1:*/callback

You can inspect or clear local MCP auth with:

nado-mcp --version
nado-mcp status
nado-mcp logout

Source checkout aliases:

npm run mcp:nado:auth -- status
npm run mcp:nado:auth -- logout

If the browser shows an error about an old, incomplete, truncated, or invalid PKCE login URL, close every old Nado MCP login tab, upgrade the package, and rerun login. Printed login URLs are single-run URLs and should not be reused:

npm install --global @nado-language/mcp@latest
nado-mcp login

Manual access-token option:

export NADO_MCP_ACCESS_TOKEN='supabase-user-access-token'
export NADO_MCP_REFRESH_TOKEN='supabase-user-refresh-token'

Password fallback:

export NADO_MCP_EMAIL='[email protected]'
export NADO_MCP_PASSWORD='password'

For local development, the server also loads ignored local env files from the current working directory or repo root:

• .env.mcp.local
• .env.local

Example .env.mcp.local:

NADO_MCP_ACCESS_TOKEN=supabase-user-access-token
NADO_MCP_REFRESH_TOKEN=supabase-user-refresh-token

Optional environment:

export NADO_MCP_SUPABASE_URL='https://ptbwzhxifxdnfmqsiugi.supabase.co'
export NADO_MCP_SUPABASE_ANON_KEY='...'
export NADO_MCP_CONNECT_URL='https://language.nado.ai.kr/mcp/connect'
export NADO_MCP_AUTH_RELAY_URL='https://language.nado.ai.kr/auth/mcp-callback'

Client Registration

Remote MCP clients should use:

https://ptbwzhxifxdnfmqsiugi.supabase.co/functions/v1/mcp

Most users should start from the Nado connection hub:

https://language.nado.ai.kr/connect

The hub collects remote MCP, local MCP, CLI, web-link fallback, and mobile/web capture entry points. Local stdio clients can also use the package flow below.

Installed package auto-registers the supported local config writers during install/update. It writes Codex Desktop, Claude Desktop, OpenCode, Cursor, Windsurf, and Gemini CLI config entries when possible. For Codex it installs and enables a local Nado Language Codex plugin with bundled MCP metadata, removes legacy direct Nado MCP registrations and stale invalid bare plugin-key sections that can create duplicate visible servers or plugin loader warnings, and if the Codex CLI is available runs codex plugin add nado-language@nado-language after writing the local marketplace. It does not open browser login during install, and it does not force an already-open AI chat to reload tools.

After install, run browser login once:

nado-mcp login

Then fully restart the AI desktop app and start a new chat/session.

If the AI app still cannot see Nado after install, login, restart, and a new chat, refresh local registration and browser login with:

nado-mcp connect

To force every supported local config writer:

nado-mcp connect all

To skip install-time auto-registration, install with:

NADO_MCP_SKIP_POSTINSTALL=1 npm install --global @nado-language/mcp

Client-specific reconnect commands are available for troubleshooting:

nado-mcp connect codex
nado-mcp connect claude
nado-mcp connect opencode
nado-mcp connect cursor
nado-mcp connect windsurf
nado-mcp connect gemini

For Codex, the command prefers the local Nado Codex plugin. If codex is on PATH, setup runs codex plugin add nado-language@nado-language after writing the local marketplace/cache. If the user only has Codex Desktop, it writes Codex Desktop's TOML config directly:

• macOS/Linux: ~/.codex/config.toml
• Windows: %USERPROFILE%\.codex\config.toml

Restart Codex Desktop after install/login completes. If a client was already open, start a new chat/session after restart. Most local MCP clients load tool definitions when the session starts, so a config that was just written may not appear inside an already-running conversation. For Codex, codex plugin list, codex mcp list, or /mcp are optional diagnostic checks to confirm the plugin/server is active in the current client. Normal users should not need them once install-time registration, login, restart, and new chat have completed. codex mcp list should show one nado_language server. If it shows both nado-language and nado_language, run nado-mcp setup codex to remove the legacy direct registration. A server can appear in Settings while still failing to reach the model tool list for the current session. On Windows, leave the Codex MCP working directory/cwd empty unless it is an existing absolute path. The Nado server does not need a working directory, and a value such as ~/code can prevent the stdio process from starting if the client does not expand it.

ChatGPT is different: it uses hosted/remote MCP apps configured from ChatGPT Apps settings, not local stdio config files. The local package can prepare local clients such as Codex, Claude Desktop, OpenCode, Cursor, Windsurf, Gemini CLI, and generic JSON-based MCP clients.

Setup without login is for advanced/manual configuration:

nado-mcp setup codex
nado-mcp setup claude
nado-mcp setup opencode
nado-mcp setup cursor
nado-mcp setup windsurf
nado-mcp setup gemini

For any other MCP-compatible client, print portable stdio config:

nado-mcp config

nado-mcp config prints all portable shapes used by common MCP harnesses:

• raw stdio command
• top-level mcpServers JSON
• direct server map JSON
• top-level mcp_servers JSON
• OpenCode mcp JSON

Use the narrower format commands when a client requires a specific shape:

nado-mcp config mcp-json
nado-mcp config mcp-map
nado-mcp config mcp-snake
nado-mcp config opencode

If the client uses a JSON file with a top-level mcpServers object:

nado-mcp setup mcp-json --file /path/to/mcp.json
nado-mcp login

Unknown clients are handled as generic MCP clients. nado-mcp setup <client-name> prints the portable config instead of failing.

Codex setup from a source checkout:

node scripts/nado-mcp-cli.mjs setup codex

Then run Codex from a shell where the auth environment variables above are set, or use the package login file. Alternatively, create .env.mcp.local in the repo root before Codex starts the MCP server. When using the installed package, nado-mcp login saves auth to the user's OS config directory and the server reads it automatically.

Troubleshooting

These commands are for diagnosis only. Normal learners should not need them after install/update, browser login, app restart, and a new chat.

Basic tool discovery:

nado-mcp doctor
nado-mcp probe list

Source checkout alias:

npm run mcp:nado:probe -- list

Authenticated account check:

nado-mcp probe whoami

Source checkout alias:

npm run mcp:nado:probe -- whoami

End-to-end admin verification. This saves a unique article, confirms no flashcards are created, and checks existing-card read/practice behavior. Mutating probe commands require --allow-write so chat agents do not use probe as a substitute for real MCP tool calls:

nado-mcp probe verify-admin --allow-write "serendipity"

Source checkout alias:

npm run mcp:nado:probe -- verify-admin --allow-write "serendipity"

The admin verification requires browser login, NADO_MCP_ACCESS_TOKEN, or NADO_MCP_EMAIL and NADO_MCP_PASSWORD, either in the current process, the package auth file, or .env.mcp.local.

Save a reading article:

nado-mcp probe save --allow-write "serendipity"

Source checkout alias:

npm run mcp:nado:probe -- save --allow-write "serendipity"

Package CLI

Normal users only need to install/update, sign in, then restart the AI app:

npm install --global @nado-language/mcp@latest
nado-mcp login

Install/update auto-registers supported local config writers for Codex Desktop, Claude Desktop, OpenCode, Cursor, Windsurf, and Gemini CLI when possible. It does not open browser login during install.

If the AI app still cannot see Nado after restart, refresh registration and sign in again:

nado-mcp connect

Generic MCP fallback:

nado-mcp config
nado-mcp login

Troubleshooting only:

nado-mcp doctor
nado-mcp probe list