# Connect AI assistants > The kinodata MCP server: setup for Claude, Claude Code, Cursor and VS Code, the tools and how they use your quota. > Documentation index for agents: https://kinodata.space/en/llms.txt — the whole documentation in one file: https://kinodata.space/en/llms-full.txt Connect kinodata to Claude, Cursor or VS Code, and the assistant finds a movie, links its IDs across every catalog and opens its title card whenever a conversation or your code needs it. The API has an MCP server for this: it speaks the open Model Context Protocol, which AI assistants use to call external tools. The server address: ```text https://api.kinodata.space/mcp ``` The MCP server is on every plan, Free included. It takes the same API key as the API — the one from your account. ## How requests are counted Every tool on the server makes ordinary requests to API v1.3 with your key. So the API and MCP share one daily quota, one rate limit and one usage chart in your account: - most tools cost one request; - `resolve_ids` costs one request per ID plus one for the whole batch; - `get_person` costs two: the person card and the first page of the filmography; - connecting and listing the tools cost nothing. The server keeps to the per-second limit itself: your account's requests go no faster than your plan allows, from all its keys, whether they come from one call or from several at once. So `resolve_ids` with 50 IDs on Free (10 requests a second) takes about five seconds but never breaks off halfway. When the daily quota runs out, the tool answers in plain text: how many requests were used and when the quota resets. The assistant passes this on by itself. Plan limits are on the [Keys and limits](https://kinodata.space/en/docs/keys.md) page. ## Connect your client The server takes the key in an `Authorization: Bearer ` header or, like the API, in `X-API-Key`. Each setup below reads the key from the `KINODATA_KEY` environment variable, as in the [Quickstart](https://kinodata.space/en/docs/quickstart.md). ### Claude Code macOS and Linux: ```bash claude mcp add --transport http kinodata https://api.kinodata.space/mcp --scope user --header "Authorization: Bearer $KINODATA_KEY" ``` Windows, PowerShell: ```powershell claude mcp add --transport http kinodata https://api.kinodata.space/mcp --scope user --header "Authorization: Bearer $env:KINODATA_KEY" ``` Where: - `kinodata` is the server's name in Claude Code. - `--scope user` makes the server available in all your projects and keeps it out of project files. Check the connection with `/mcp` in Claude Code. ### Cursor Open `~/.cursor/mcp.json` and add the server: ```json { "mcpServers": { "kinodata": { "url": "https://api.kinodata.space/mcp", "headers": { "Authorization": "Bearer ${env:KINODATA_KEY}" } } } } ``` Cursor fills in the key from the `KINODATA_KEY` environment variable. Cursor itself must see the variable, so set it system-wide, not only in an open terminal. ### VS Code Run **MCP: Open User Configuration** and add this to the `mcp.json` it opens: ```json { "inputs": [ { "type": "promptString", "id": "kinodata-key", "description": "kinodata API key", "password": true } ], "servers": { "kinodata": { "type": "http", "url": "https://api.kinodata.space/mcp", "headers": { "Authorization": "Bearer ${input:kinodata-key}" } } } } ``` VS Code asks for the key the first time the server starts, and the key never lands in the file. ### Claude In claude.ai and the Claude apps, add the server as a custom connector: 1. Open **Customize → Connectors** and click **Add custom connector**. 2. Enter `https://api.kinodata.space/mcp` as the server URL. 3. Under **Authentication**, choose **No sign-in**. 4. Under **Request headers**, add `authorization` with the value `Bearer ` followed by your key — the whole value, including the word `Bearer` and the space. **Request headers** is in beta and not every account has it yet. If you don't see it, connect the server in Claude Code, or in the Claude desktop app through the `mcp-remote` bridge (needs Node.js). In `claude_desktop_config.json`: ```json { "mcpServers": { "kinodata": { "command": "npx", "args": ["-y", "mcp-remote", "https://api.kinodata.space/mcp", "--header", "Authorization:${AUTH_HEADER}"], "env": { "AUTH_HEADER": "Bearer your_key" } } } } ``` There are no spaces around the colon in `args` on purpose: on Windows the app doesn't escape spaces in arguments, and the header breaks. A space inside `AUTH_HEADER` is fine. ### ChatGPT ChatGPT can't connect yet: it doesn't send a key in a header, and the server has no OAuth sign-in. ## Tools | tool | what it does | |---|---| | `resolve_ids` | A title's IDs in every catalog, up to 50 IDs at once. | | `search_titles` | Movies and series by title in Russian or English, typos tolerated. | | `get_title` | A title card: titles, year, genres, countries, ratings, overview, directors and leading cast. | | `get_title_section` | One long section of a title, page by page: cast, crew, awards, episodes, facts, quotes, media, sites, tags. | | `find_titles` | Titles by catalog conditions: kind, genres, countries, years, rating and vote count, a Kinorium tag, presets. | | `get_related_titles` | Similar titles and the franchise. | | `search_persons` | Actors, directors and other film people by name. | | `get_person` | A person card — dates, age, height, family with the relatives' gender, awards by ceremony, trivia, links (the catalogs, Wikipedia, Wikidata, their website and social networks) — and their filmography, page by page. | | `get_collection` | Collections: the list of them, or the titles of one, such as `daily-trending-titles` — trending today. | Answers are compact: the server leaves out empty fields and returns long lists in pages. ## What to ask - "Give me the Kinopoisk IDs for tt0111161, tt0068646 and tt0468569." - "Korean thrillers from the 2010s rated above 7.5 on Kinopoisk." - "Who directed *Stalker*, and what else did he make after 1970?" - "What's trending today, and is there any anime in it?" - "How many seasons and episodes does *Breaking Bad* have?" ## Keep your key safe - Keep the key in the client's user settings or in an environment variable. Don't put it in a project `mcp.json` that goes into a repository, and don't paste it into a chat with the assistant. - Send the key in a header only. The server rejects an address with the key in the query string. - Overviews and facts from the catalogs are third-party text. The server strips links, images and HTML from them, but if the assistant ever suggests an action "from a movie's overview", don't agree to it. ## If it doesn't connect | response | when | what to do | |---|---|---| | `401` | The key is missing, wrong or revoked. | Check the header: `Authorization: Bearer` and the whole key from your account. | | `400` | The key was sent in the address. | Remove it from the address and send it in a header. | | `429` | 30 requests with a wrong key came from your address within a minute. | Wait a minute and check the key. | ## Next - [Keys and limits](https://kinodata.space/en/docs/keys.md) — plan limits and how to watch your balance. - [IDs in every catalog](https://kinodata.space/en/docs/ids.md) — the endpoint behind `resolve_ids`.