Підключення до справжнього хоста

Хост — це застосунок, усередині якого зрештою опиняється ваш сервер: Claude Desktop, Claude Code, IDE. Саме з хостом говорить користувач. Усередині нього MCP-клієнт запускає ваш сервер як дочірній процес і спілкується з ним через stdin і stdout цього процесу.

Отже, підключення до хоста — це одна дія: ви повідомляєте йому команду, яка запускає ваш сервер. Усе на цій сторінці (дві команди CLI, три JSON-файли) — це різні місця, куди вписати ту саму команду.

Один сервер, усі хости

from mcp.server import MCPServer

mcp = MCPServer("Bookshop")

CATALOG = {
    "Dune": "Frank Herbert",
    "Neuromancer": "William Gibson",
    "The Left Hand of Darkness": "Ursula K. Le Guin",
}


@mcp.tool()
def search_books(query: str) -> list[str]:
    """Search the catalog by title or author."""
    needle = query.lower()
    return [title for title, author in CATALOG.items() if needle in title.lower() or needle in author.lower()]


@mcp.tool()
def get_author(title: str) -> str:
    """Look up the author of a book in the catalog."""
    if title not in CATALOG:
        raise ValueError(f"No book titled {title!r} in the catalog.")
    return CATALOG[title]


@mcp.resource("catalog://titles")
def titles() -> str:
    """Every title in the catalog, one per line."""
    return "\n".join(sorted(CATALOG))


if __name__ == "__main__":
    mcp.run()

Два інструменти й один ресурс в одному файлі. Для кожного хоста нижче в цьому файлі важливі три речі:

• mcp.run() без аргументів запускає stdio-сервер: він блокує виконання, читає повідомлення протоколу зі stdin і пише їх у stdout. Саме цим транспортом говорить кожен хост на цій сторінці. Хост запускає ваш файл як дочірній процес і володіє цими двома каналами, тому підключення завжди зводиться до «ось команда». Порт обирати не потрібно, і ніщо на порту не слухає.
• run() стоїть під if __name__ == "__main__":. Усе, що нижче, імпортує цей файл, а не виконує його, тож незахищений run() запустив би сервер, щойно будь-що завантажить модуль.
• Об'єкт сервера — глобальна змінна рівня модуля з іменем mcp. Саме це ім'я шукає mcp run (server і app теж підходять). Назвете інакше — вкажіть ім'я явно: mcp run server.py:bookshop.

Це останній рядок Python на цій сторінці. Далі — лише налаштування хостів.

Команда запуску

Кожен хост нижче отримує ту саму команду:

uv run --with "mcp[cli]" mcp run /absolute/path/to/server.py

Одна команда для всіх, бо uv run --with розв'язує SDK у свіже середовище на місці: вона працює з будь-якого каталогу й не потребує ні проєкту, ні віртуального середовища, яке треба активувати. Тут це важливіше, ніж деінде, бо хост запускає ваш сервер зі свого робочого каталогу з майже порожнім середовищем, а не з вашої оболонки.

Це також команда, яку mcp install записує за вас у конфігурацію Claude Desktop (нижче), тож те, що ви набираєте вручну, і те, що генерує утиліта, збігаються — за винятком точної фіксації версії, яку додає утиліта.

Claude Desktop

Єдиний хост, який SDK може налаштувати за вас:

uv run mcp install server.py

От і все. mcp install імпортує файл, щоб прочитати ім'я сервера, знаходить файл конфігурації Claude Desktop і записує в нього команду запуску. Дорогою вона перетворює ваш шлях на абсолютний, тож робити це самим не потрібно.

Жодної магії тут немає. Ось запис, який вона створює:

{
  "mcpServers": {
    "Bookshop": {
      "command": "/absolute/path/to/uv",
      "args": [
        "run",
        "--frozen",
        "--with",
        "mcp[cli]==2.0.0",
        "mcp",
        "run",
        "/absolute/path/to/server.py"
      ]
    }
  }
}

Це команда запуску з розділу вище з трьома доповненнями: абсолютний шлях до uv, --frozen, щоб uv ніколи не переписував lock-файл, який випадково опиниться поруч, і точна фіксація встановленої у вас версії mcp. Запис потрапляє в claude_desktop_config.json, який лежить тут:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

Цей файл можна написати й вручну. mcp install існує, щоб ви не припустилися класичної помилки (відносного шляху), поки це робите.

Повністю завершіть Claude Desktop (а не лише закрийте вікно) і відкрийте знову.

Claude Code

Файлу для редагування немає. Зареєструйте сервер через CLI claude; усе після -- — це команда запуску.

claude mcp add bookshop -- uv run --with "mcp[cli]" mcp run /absolute/path/to/server.py

Виконайте /mcp у сесії Claude Code, щоб переконатися, що bookshop підключено, а його інструменти перелічено.

Cursor

Створіть .cursor/mcp.json у корені проєкту.

{
  "mcpServers": {
    "bookshop": {
      "command": "uv",
      "args": ["run", "--with", "mcp[cli]", "mcp", "run", "/absolute/path/to/server.py"]
    }
  }
}

Ті самі command та args під тим самим ключем mcpServers, що й у Claude Desktop. Сервер з'являється в налаштуваннях MCP у Cursor з обома інструментами в списку.

VS Code

Створіть .vscode/mcp.json у корені проєкту.

{
  "servers": {
    "bookshop": {
      "type": "stdio",
      "command": "uv",
      "args": ["run", "--with", "mcp[cli]", "mcp", "run", "/absolute/path/to/server.py"]
    }
  }
}

Дві відмінності від файлу Cursor, і це єдині дві: ключ-обгортка — servers, а не mcpServers, і кожен запис оголошує свій type. Підтвердьте запит про довіру, і команда MCP: List Servers у палітрі команд покаже, що bookshop працює.

Сервер не з'являється

Перш ніж чіпати конфігурацію будь-якого хоста, виконайте команду запуску самі:

uv run --with "mcp[cli]" mcp run /absolute/path/to/server.py

Нічого не виводиться, і команда не завершується. Ця тиша правильна: stdio-сервер чекає, доки хост першим заговорить у stdin (Ctrl-C, щоб зупинити). Справжня помилка — це трасування стека або негайний вихід, і тепер її можна прочитати, а не вгадувати через хост.

Коли ця команда сидить і чекає, залишається майже завжди одне з трьох:

• Відносний шлях. Хост запускає ваш сервер зі свого робочого каталогу, а не з того, з якого ви його реєстрували. server.py там, де потрібен /absolute/path/to/server.py, — найпоширеніша причина збою. Якщо хост не знаходить ще й uv, цей шлях теж має бути абсолютним.
• Хост досі працює зі старою конфігурацією. Хости читають конфігурацію під час запуску. Зокрема Claude Desktop треба повністю завершити (а не лише закрити вікно) і відкрити знову, перш ніж зміна в claude_desktop_config.json набуде чинності.
• Щось потрапило в stdout поза проміжком перенаправлення. У stdio stdout — це і є протокол. Під час обслуговування SDK перенаправляє скинутий (flushed) сторонній вивід у stderr, але вивід, скинутий у stdout до того (скрипт-обгортка, що робить echo, print() на етапі імпорту в небуферизованому процесі), або буферизований print(), що зливається під час завершення інтерпретатора, передає хосту зіпсоване повідомлення, і той розриває з'єднання. Пишіть логи зі стандартною конфігурацією logging, чий обробник stderr скидає кожен запис; власні обробники теж мають уникати stdout. Докладніше — на сторінці Логування.

Claude Desktop веде окремий лог для кожного сервера: mcp-server-<NAME>.log — це stderr вашого сервера, поруч із mcp.log для з'єднань, у ~/Library/Logs/Claude на macOS і %APPDATA%\Claude\logs на Windows.

Для всього, що виходить за межі цих трьох випадків, є сторінка Усунення несправностей.

Підсумки

• Хост (Claude Desktop, IDE) виконує MCP-клієнт, який запускає ваш сервер як дочірній процес через stdio. Підключитися означає дати йому одну команду запуску.
• Ця команда — uv run --with "mcp[cli]" mcp run /absolute/path/to/server.py: жодного venv для активації, працює з будь-якого каталогу.
• Claude Desktop — єдиний хост, який mcp install налаштовує за вас. Вона записує ту саму команду (плюс абсолютний шлях до uv, --frozen і точну фіксацію встановленої у вас версії) у claude_desktop_config.json, тож вам цього робити не доведеться.
• Claude Code — це claude mcp add bookshop -- <launch command>. Cursor — .cursor/mcp.json з ключем mcpServers. VS Code — .vscode/mcp.json з ключем servers, кожен запис із type.
• Скрізь абсолютні шляхи, перезапуск хоста після редагування конфігурації, і ніщо, крім SDK, ніколи не пише в stdout.

Кожен хост на цій сторінці підключився до того самого файлу тією самою командою. Про те, що цей файл може надавати, — решта цієї документації: Інструменти, Ресурси і всі транспорти, крім stdio, на сторінці Запуск сервера.