Основы работы с API: HTTP, JSON и аутентификация

Мы настроили рабочее пространство в VS Code и готовы переходить к самому важному — «общению» нашего будущего агента с внешним миром. Чтобы ИИ-агент мог проверять погоду, отправлять сообщения в мессенджеры или получать данные из базы, он должен освоить универсальный язык обмена информацией.

В основе этого взаимодействия лежит API (Application Programming Interface). Представьте, что API — это розетка: вы втыкаете в неё штекер (запрос) и получаете ток (данные), не задумываясь, как работает электростанция. Для MCP-агентов это единственный способ выйти за пределы чата и начать действовать.

Анатомия HTTP-запроса

Почти все современные API работают через протокол HTTP. Каждый раз, когда агент обращается к сервису, он отправляет HTTP-запрос.

Основные элементы запроса, которые мы будем прописывать в коде сервера:

• Метод — действие (что сделать?).
• URL — адрес (куда отправить?).
• Заголовки (Headers) — метаданные (кто отправляет и в каком формате?).
• Тело (Body) — сами данные (например, текст сообщения).

Как происходит этот цикл, можно увидеть на Схеме 1.

Методы GET и POST

Для разработки MCP-серверов важно различать два основных метода:

1. GET — только получение данных. Запросить курс валют или прогноз погоды. Это «безопасный» метод: он ничего не меняет на сервере.
2. POST — изменение или создание. Отправить письмо, создать задачу в Jira, сохранить лог.

⚡️ Правило 2026 года: никогда не используйте GET для действий, которые меняют данные. Иначе агент может случайно вызвать удаление или покупку, просто «проверяя» ссылку.

JSON — язык, на котором говорят нейросети

Сервер возвращает ответ в формате JSON (JavaScript Object Notation). Это текстовый формат, который обожают LLM: он строгий, лаконичный и легко читается кодом.

JSON строится на парах «ключ: значение».

Валидный JSON (агент поймет):

{
  "id": 1024,
  "username": "ai_developer",
  "is_active": true,
  "skills": ["Python", "MCP", "TypeScript"]
}

Ошибочный JSON (сервер упадет):

{
  id: 1024, // Ошибка: ключи без кавычек
  "username": 'ai_developer', // Ошибка: одинарные кавычки запрещены
  "is_active": true
}

Даже лишняя запятая в конце списка превратит ваш MCP-сервер в «тыкву». Будьте внимательны к синтаксису.

Безопасность и аутентификация

Чтобы API не пользовался кто угодно, сервисы требуют подтвердить личность. Это называется аутентификация.

1. API-ключ — ваш персональный пароль, длинная строка символов.
2. Аутентификация по токену (Bearer Token) — современный стандарт. В заголовках запроса это выглядит так: Authorization: Bearer ваш_длинный_ключ_здесь

🛡 Безопасность: никогда не пишите ключи прямо в коде (hardcode). Если вы выложите такой проект на GitHub, ваш баланс улетит в трубу за считанные минуты. Мы научимся использовать переменные окружения (.env) в следующих уроках.

Статус-коды: быстрый аудит ответа

Сервер всегда отвечает цифровым кодом. Запомните базу:

• 200 — Успех. Все работает.
• 400 — Ошибка в запросе. Вы отправили «кривой» JSON.
• 401 — Ошибка авторизации. Неверный API-ключ.
• 404 — Не найдено. Ошибка в URL.
• 500 — Проблема на сервере. Вы ни при чем, нужно подождать.

Практика: делаем запрос из VS Code

Проверим теорию делом. Используем утилиту curl (она встроена в терминал VS Code).

1. Откройте терминал в VS Code (`Ctrl + ``).
2. Введите команду для получения случайной цитаты: curl https://api.quotable.io/random
3. Нажмите Enter.

Если вы увидели в терминале текст в фигурных скобках {...} — поздравляю, вы успешно взаимодействовали с API!

Теперь мы знаем, как данные перемещаются между системами. Но как заставить ИИ не просто «видеть» эти данные, а правильно ими пользоваться? В следующем уроке разберем искусство управления вниманием нейросети — базовый промпт-инжиниринг.