Connect AI assistants

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:

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 page.

Connect your client#

The server takes the key in an Authorization: Bearer <key> 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.

Claude Code#

macOS and Linux:

claude mcp add --transport http kinodata https://api.kinodata.space/mcp --scope user --header "Authorization: Bearer $KINODATA_KEY"

Windows, 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:

{
  "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:

{
  "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:

{
  "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#

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#

Next#

• Keys and limits — plan limits and how to watch your balance.
• IDs in every catalog — the endpoint behind resolve_ids.