Connect an AI assistant

Yalango speaks MCP, the protocol assistants use to call outside tools. Once connected, you can ask an assistant to add the words from an article to a deck, clean up a card's translation, or tell you what you have due for review - and it does the work in your account directly, instead of handing you a list to copy in.

There are two ways to connect, and they reach exactly the same tools:

• Sign in - for ChatGPT, Claude.ai, Le Chat and any assistant that supports OAuth. You paste one address, sign in to Yalango, and choose what it may do. Nothing to copy.
• API key - for Cursor, Claude Code, Gemini CLI, VS Code, Codex, Windsurf and other clients where you can set a header yourself. The same key works with the REST API.

The endpoint

https://yalango.com/mcp

It is a streamable HTTP MCP server. Both ways of connecting use this one address.

Connect ChatGPT

1. In ChatGPT, open Settings > Apps & Connectors and turn on developer mode under Advanced settings if your plan requires it.
2. Choose Create and enter https://yalango.com/mcp as the MCP server URL. Choose OAuth as the authentication.
3. ChatGPT opens a Yalango page. Sign in if you are not already, tick the permissions you want, and choose Allow.

Connect Claude.ai or Claude Desktop

1. Open Settings > Connectors and choose Add custom connector.
2. Enter https://yalango.com/mcp as the URL and leave the advanced settings empty.
3. Choose Connect, then sign in to Yalango and choose Allow.

Connect Mistral Le Chat

1. Open Intelligence > Connectors and choose Add connector.
2. Switch to Custom MCP connector, enter a name, and set the server URL to https://yalango.com/mcp.
3. Choose Connect. When asked for an authentication method, pick OAuth if you are not prompted automatically, then sign in to Yalango and choose Allow.

Choosing permissions

When an assistant connects by signing in, Yalango always lists every permission. Scopes the assistant named start ticked; if it named none, only the read permissions do. Tick the others if you want it to be able to create decks, add cards or build texts, tables, notebooks and folders, and untick anything you do not want to grant.

The page will say Yalango has not verified the app. That is true of every app connected this way: the name shown is what the app calls itself. Only allow a connection you started yourself. You need a verified email address to allow one.

Get a key

Create an API key in settings. Tick every scope you want the assistant to have, because scopes decide which tools it can even see:

Scope	Tools it unlocks
decks:read	list_decks, get_deck, list_custom_fields
cards:read	list_cards
vocabulary:read	search_vocabulary, get_review_summary
decks:write	create_deck, update_deck, create_custom_field, update_custom_field, delete_custom_field
cards:write	add_cards, update_cards, delete_cards
texts:read	list_texts, get_text
texts:write	create_text, update_text, delete_text
tables:read	list_tables, get_table, list_table_rows
tables:write	create_table, update_table, write_table_rows, delete_table
notebooks:read	list_notebooks, get_notebook, get_notebook_page, list_pdfs
notebooks:write	create_notebook, update_notebook, write_notebook_page, upload_notebook_image, upload_pdf, delete_notebook_page, delete_notebook
folders:read	list_folders, get_folder
folders:write	create_folder, update_folder, move_to_folder, delete_folder
languages:read	list_my_languages
languages:write	add_language
Any scope	get_yalango_guide

A tool you have not granted is not just refused - it never appears in the assistant's list, so it will not try to use it and will not invent a workaround. If you would rather the assistant could only look and never touch, give it the read scopes on their own.

Connected before texts, tables, notebooks and folders were added? Your existing connection keeps the permissions it was given, so the new tools will not appear. Create a new API key with the new scopes, or reconnect: in ChatGPT, remove the connector under Apps & Connectors and create it again (Reconnect reuses ChatGPT's cached scope list, so the new read permissions stay unticked until you do). In other assistants, disconnect Yalango and connect again, then tick the new permissions.

The same scopes are the permissions on the sign-in page, so this table applies to both ways of connecting.

Connect Cursor

Add this to ~/.cursor/mcp.json, or to .cursor/mcp.json inside a project:

{
  "mcpServers": {
    "yalango": {
      "url": "https://yalango.com/mcp",
      "headers": {
        "Authorization": "Bearer yal_your_key_here"
      }
    }
  }
}

Restart Cursor, then enable the server under Customize > MCPs.

Connect Claude Code

claude mcp add --transport http yalango https://yalango.com/mcp \
  --header "Authorization: Bearer yal_your_key_here"

Connect Gemini CLI

The Gemini web and mobile apps cannot add custom MCP servers. These steps are for Gemini CLI only.

Add this to ~/.gemini/settings.json, or to .gemini/settings.json inside a project:

{
  "mcpServers": {
    "yalango": {
      "httpUrl": "https://yalango.com/mcp",
      "headers": {
        "Authorization": "Bearer yal_your_key_here"
      }
    }
  }
}

Restart Gemini CLI. To sign in with OAuth instead, leave out headers and run /mcp auth yalango in the CLI.

Connect VS Code (GitHub Copilot)

Add this to .vscode/mcp.json, or open your user config with MCP: Open User Configuration:

{
  "inputs": [
    {
      "type": "promptString",
      "id": "yalango-key",
      "description": "Yalango API key",
      "password": true
    }
  ],
  "servers": {
    "yalango": {
      "type": "http",
      "url": "https://yalango.com/mcp",
      "headers": {
        "Authorization": "Bearer ${input:yalango-key}"
      }
    }
  }
}

Use Copilot Chat in Agent mode so the Yalango tools are available.

Connect OpenAI Codex CLI

Add this to ~/.codex/config.toml:

[mcp_servers.yalango]
url = "https://yalango.com/mcp"
bearer_token_env_var = "YALANGO_API_KEY"

Set YALANGO_API_KEY in your environment to your API key so the token is not stored in the file. Restart Codex after you change the environment.

Connect Windsurf

Add this to ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "yalango": {
      "serverUrl": "https://yalango.com/mcp",
      "headers": {
        "Authorization": "Bearer yal_your_key_here"
      }
    }
  }
}

Save the file, then refresh under Windsurf Settings > Cascade > MCP servers.

Connect another client

Any client that supports a remote MCP server over streamable HTTP will work. If it supports OAuth, point it at https://yalango.com/mcp and it will find the sign-in page on its own. Otherwise have it send the header:

Authorization: Bearer yal_your_key_here

Clients that only speak stdio can bridge to it with mcp-remote.

What the assistant can do

Tool	What it does
list_decks	List your decks, most recently updated first
get_deck	Read one deck, its languages and its card count
list_cards	List the cards in a deck
list_custom_fields	List a deck's custom fields and their ids
search_vocabulary	Look a word up across everything you study
get_review_summary	See what is due now and what is coming
create_deck	Create a private deck
update_deck	Change a deck's name, description or tags
add_cards	Add up to 100 cards at once
update_cards	Change up to 100 cards at once
delete_cards	Delete up to 100 cards at once
create_custom_field	Add a custom field to a deck
update_custom_field	Rename a custom field, or make it the field the Cloze game uses
delete_custom_field	Delete a custom field and its values
list_texts, get_text	List your reading texts and read one
create_text, update_text, delete_text	Write, edit and delete a reading text
list_tables, get_table, list_table_rows	List your tables and read their columns and rows
create_table, update_table	Create a table, rename it, and add, rename, delete or reorder columns
write_table_rows	Add, edit and delete up to 100 rows at once
delete_table	Delete a table and all of its rows
list_notebooks, get_notebook, get_notebook_page	List your notebooks, see their outline and read a page
create_notebook, update_notebook	Create a notebook, rename it, and manage its sections
write_notebook_page	Create or rewrite a page with any block the editor has: text, headings, example sentences, videos, images, PDFs and your decks, tables and texts
upload_notebook_image, upload_pdf, list_pdfs	Upload an image or PDF for a notebook page, and list your PDFs. Premium only
delete_notebook_page, delete_notebook	Delete a page, or a whole notebook
list_folders, get_folder	List your folders and see what is in them
create_folder, update_folder, delete_folder	Create, rename, reorder and delete empty folders
move_to_folder	Move a deck, table, text, notebook or folder into a folder
list_my_languages	List the languages you study and which one was last active
add_language	Add a language you want to study to your account
get_yalango_guide	Read how Yalango works and how to structure content. Always available

Cards added this way are ordinary cards. They get pronunciation audio and pinyin the same way cards added in the web app do, and they enter your review queue on the same schedule.

Things worth knowing

Deleting has no undo. delete_cards takes a card's review history with it, and delete_custom_field clears that field on every card in the deck. The same goes for deleting a text, table, notebook, page or folder, for deleting a table column or a notebook section through update_table or update_notebook, and for deleting rows. The delete tools are marked as destructive so a well-behaved client asks you first, but that is the client's choice, not something Yalango can enforce. Read back what it says it is about to delete.

Ask it to check for duplicates. Your vocabulary is shared across decks, so the same word added twice comes up twice in every review session. Assistants are told to call search_vocabulary before adding, which needs vocabulary:read - without that scope it cannot check.

A duplicate can slip in after a timeout. If an add_cards call times out, the cards may have been written anyway. Have the assistant look before it retries.

Languages are fixed once a deck has cards. Getting source and target the wrong way round is the one mistake that cannot be corrected later, so confirm which language is which when it creates a deck.

Limits

MCP calls draw on the same rate limits as the REST API - 60 requests a minute and 5000 a day, with writes weighted more heavily than reads. See Errors and rate limits.

Your plan's deck and card limits still apply. An assistant that hits one gets an error explaining which limit it was, and will normally tell you rather than silently stopping.

Revoking access

Assistants you connected by signing in are listed under Connected apps in Settings > API. Choose Disconnect and the assistant loses access on its next request.

For a key, revoke it in the same place and the connection dies immediately. Since one key is one connection, you can give each assistant its own key and cut off just that one.

An OAuth connection only works with the MCP endpoint. To call the REST API from a script, use an API key.

Next steps

• Create and manage API keys
• The Yalango API
• Errors and rate limits