# Инструменты и схемы MCP

Посмотрите на аргументы FlashData MCP, дефолты, считывания учетных записей, состояния работы и результаты поиска.

Каноническая ссылка: https://flashdata.dev/ru/docs/mcp

[Выберите клиент MCP и подключитесь](https://flashdata.dev/ru/docs/integrations/mcp-clients/reference.md)

[OAuth, Codex, OpenClaw и API-ключ](https://flashdata.dev/ru/docs/guides/agent-access/reference.md)

<a id="connect"></a>

## Транспорт и аутентификация

В размещенной конечной точке MCP используется потоковая HTTP. Соединения API-ключа отправляют X-API-Key; доступ к инструменту следует за разрешениями источника ключа и доступными кредитами.

### Streamable HTTP

```text
URL: https://data.flashdata.dev/mcp
X-API-Key: <your API key>
```

Храните фактический ключ FlashData API в конфигурации учетных данных клиента. Не ставьте это в разговор или инструмент аргументов. Этот раздел охватывает соединения API-ключа; руководство по доступу агента охватывает вход OAuth и протестированные конфигурации Codex и OpenClaw. youtube_download поддерживает асинхронные загрузки мультимедиа с соответствующим разрешением API-ключа.

<a id="tools"></a>

## Инструменты запроса

Ваш клиент находит инструменты, предоставленные ключом. Все шесть Google и восемь инструментов YouTube по умолчанию работают в режиме реального времени, а также принимают mode: async. submit_batch поддерживает обе группы. youtube_download использует формальную загрузку API, требует хранения клиентов и поддерживает работу асинхронизации или submit_batch. Модель может выбирать и комбинировать инструменты для выполнения задачи.

google_search · google_images · google_news · google_shopping · google_videos · google_places

youtube_search · youtube_search_extended · youtube_metadata · youtube_transcript · youtube_captions · youtube_trainability · youtube_channel · youtube_suggestions · youtube_download

<a id="parameters"></a>

## Инструментальные аргументы

Поместите поля запросов, такие как запрос, число, язык и режим, непосредственно в объект аргументов инструмента, без обертки парам REST API. Имя инструмента запроса выбирает его источник; только записи в submit_batch требуют источника. Ключи API и callback_url не являются аргументами инструмента. Приведенные ниже примеры JSON являются объектами аргументов для client.callTool ({имя, аргументы }).

Используйте булевы JSON и целые числа, а не строки. Неизвестные поля отклоняются. Инструменты 14 принимают mode: realtime или асинхронизацию, по умолчанию в режиме реального времени. Записи Batch не принимают режим.

| Инструмент | Обязательно | Факультативные аргументы и дефолты |
| --- | --- | --- |
| youtube_download | video_id, storage | Поддерживает только асинхронизацию (по умолчанию). download_type: audio_video (по умолчанию)/video/audio. video_quality: <=720 по умолчанию; best/worst или <=, ==, >= с 144/360/480/720/1080/1440/2160/4320. FPS: те же сравнения с 1–240. output_formatmp4 (по умолчанию)/webm/mkv для видео, m4a (по умолчанию)/mp3/opus Для аудио. audio_language: default/original; audio_quality: best/320/256/192/128Только аудио. yt_dlp_format: вплоть до 1024 символы, перевешивает качество, fps и выбор языка. Omit video_quality/fps для аудио и audio_language только для видео. хранение требуется и соответствует Загрузить API params.storage. start_at/end_at: HH:MM:SS, до часов 12; end_at должен следовать start_at. upload_metadata: булевый, по умолчанию false. Каждая партия загрузки требует хранения. Нет browser_delivery или callback_url. |
| storage | storage_type, storage_url | storage_url - это ваше имя ведра (Azure: контейнер), а не локальный каталог. storage_type: s3/s3_compatible/oss/gcs/azure/cos/bos/tos; дополнительный object_prefix. S3, S3-совместимые, OSS, COS, BOS и TOS используют access_key/secret_key с применимым region/endpoint_url. GCS использует service_account (project_id, client_email, private_key); Azure использует account_name и контейнер sas_token с разрешением на запись. Конечная точка должна быть достижима от работника. Прочитайте учетные данные из вашей конфигурации хранилища; не вставляйте их в чат или эхо. |
| google_* | query | Запрос: символы 1–2, 000. gl: двухбуквенная страна; hl: код языка символов 1–35; location/tbs: символы 1–200; num/page: целые числа 1–100; автокорректный: булевый. Опущенные опции используют поведение поставщика поиска, при этом не гарантируется фиксированная страна, язык или количество результатов. |
| youtube_search | query | Запрос: 1–2, 000 символы. max_results: 1–20, по умолчанию 20; фильтры: объект фильтра, опущенный или null без фильтров. |
| youtube_search_extended | query | Запрос: 1–2, 000 символы. max_results: 1–700, по умолчанию 20; фильтры: те же, что и стандартный поиск. |
| youtube_metadata | video_id | include_formats и include_chapters: booleans, оба по умолчанию true. |
| youtube_transcript | video_id | Омит язык предпочесть эн-ориг, затем эн, возвращая один трек. С auto=true каждый код предпочитает свой -orig трек, затем простой код; явный -orig и auto=false остаются точными. Arrays пробует все запрошенные языки 1–10 и возвращает дорожки и ошибки в порядке. автопо умолчанию true для автоматических подписей. |
| youtube_captions | video_id | Омит язык предпочесть эн-ориг, затем эн, возвращая один трек. С auto=true каждый код предпочитает свой -orig трек, затем простой код; явный -orig и auto=false остаются точными. Arrays пробуют все запрошенные языки 1–10 и возвращают дорожки и ошибки в порядке. автопо умолчанию false для подписей, предоставляемых загрузчиком. |
| youtube_trainability | video_id | Никаких дополнительных аргументов, кроме режима. Сообщает о классификации лицензий Creative Commons; не предоставляет разрешения на обучение. |
| youtube_channel | handle | ручка: символы 1–100; video_limit: 1–100, 20 по умолчанию. |
| youtube_suggestions | query | Запрос: символы 1–2, 000; язык: по умолчанию en; регион: двухбуквенный код страны, по умолчанию US. |

video_id - это 11-символ YouTube ID с использованием букв, цифр, подчеркиваний или дефисов; поставьте ID, а не видео URL. Каждый языковой код - это символы 1–35, использующие буквы, цифры или дефисы. Для субтитров auto=true выбирает автоматические подписи, а false выбирает подписи, предоставляемые загрузчиком, без автоматического резервного копирования между ними. Для языковых массивов проверяйте ошибки, даже если работа удалась.

### Фильтры поиска YouTube

filters.type: video/channel/playlist/movie; upload_date: today/last_hour/this_week/this_month/this_year; продолжительность: <4, 4-20 или >20; sort_by: rating/relevance/view_count/upload_date. Флаги функций являются булевыми; true требует этой функции: 360, 3d, 4k, creative_commons, hd, hdr, live, location, buy, subtitles, vr180.

<a id="account"></a>

## Account Insights (бесплатно)

get_balance считывает баланс вашего общего счета; get_pricing оценивает затраты на запрос; get_limits считывает лимиты плана и текущие ожидающие работы; get_usage суммирует последние дни 7 по умолчанию с максимальным окном 31-день. Использование включает в себя все ключи учетной записи для источников, авторизованных вызывающим ключом, и может быть отложено.

get_balance и get_limits принимают {}. get_pricing принимает необязательный источник; опускает его для всех источников запросов MCP, авторизованных вашим ключом. request_count - это целое число от 1 до 100000, по умолчанию 1; каждая страница или пакетный элемент считается отдельным запросом. get_usage принимает необязательный источник; опускает его для всех авторизованных источников. Включает использование youtube_download. Ценообразование загрузки возвращает creditsPerTb (1 TB = 10^12 байты); скачивает резервные кредиты и рассчитывается по фактически загруженным байтам. request_count не применяется к загрузкам, а estimatedCredits является null.

get_usage from/to должен быть временными метками UTC ISO, такими как 2026-09-21T00:00:00Z, необязательно с дробными вторыми цифрами 1–3. от инклюзивного до эксклюзивного, округленного до минут. Окно по умолчанию - это дни 7, а максимум - дни 31. Семь дней спустя, а семь дней спустя, и только до, с семи дней раньше. Прочитайте ответ from/to для эффективного окна.

<a id="jobs"></a>

## Рабочие места и большие результаты

Запрос на асинхронизацию возвращает идентификатор вакансии; передайте его как job_id в get_job для чтения job.status. Завершенные задания включают в себя первоначальный ответ на запрос в выходе. Для загрузок выходом является манифест загрузки: output.results[0].file_url указывает на хранилище клиента, с file_size, downloaded_bytes и md5. Частные файлы требуют аутентификации вашего хранилища. Результаты JSON сохраняются в течение часов 24; сохранение и доступ к медиафайлам следуют вашим политикам хранения. submit_batch принимает по крайней мере один запрос Google или YouTube (включая загрузку), с исходными и плоскими аргументами по каждой записи. Каждая запись оплачивается отдельно, и применяются пакетные и ожидаемые лимиты вашего плана. Чтение за работу больше не взимается. Bulk не является инструментом MCP.

Замените пример job_id, result_id и компенсируйте значениями из вашего ответа. Прочитайте следующий фрагмент, не возвращая запрос.

Большие ответы включают текстовый фрагмент JSON, result_id и next_offset. Звоните get_result с тем же ключом и возвращенным смещением result_id. является неотрицательным целым числом, по умолчанию 0; используйте предыдущий next_offset для продолжения. предел - это целое число от 1 до 16000, по умолчанию 16000, измеренное в единицах кода UTF-16, а не байтах или строках результатов. Сопоставьте куски по порядку перед разбором JSON; next_offset = null обозначает конец. Результаты кэшируются на 10 минуты, максимум четыре больших результата на ключ, и могут быть выселены раньше. Чтение кусков не повторяет запрос или начисление кредитов.

[Обработка файла ID? Используйте Bulk HTTP API](https://flashdata.dev/ru/docs/reference/bulk-processing/reference.md)

<a id="billing"></a>

## Billing и ошибки

Запросы используют цены на кредиты вашего существующего плана без дополнительной платы MCP. Ошибки инструмента устанавливают isError и сохраняют статус HTTP и запрашивают ID. Восстановите кредиты за недостаточный баланс и проверьте ключевые разрешения на ошибки доступа.

Тайм-аут или потерянное соединение не означает, что запрос не был выполнен. Для query_outcome_unknown, проверьте Запрос History в консоли, прежде чем принять решение о повторной отправке. Не повторяйте автоматически оплаченные заявки; считывания существующих вакансий или кусков могут быть перепроверены. Ответы в верхнем потоке ограничены 4 MiB, поэтому ограничивайте размер поиска; негабаритные ответы, возможно, уже были заряжены.

[Основные коды состояния HTTP](https://flashdata.dev/ru/docs/errors/reference.md#status-codes) · [Правила повторного использования](https://flashdata.dev/ru/docs/errors/reference.md#retries)

### youtube_download · arguments JSON

```json
{
  "video_id": "FUfGcZ092b0",
  "download_type": "audio_video",
  "video_quality": "<=360",
  "output_format": "mp4",
  "storage": {
    "storage_type": "s3",
    "storage_url": "your-video-bucket",
    "object_prefix": "mcp-downloads",
    "access_key": "YOUR_STORAGE_ACCESS_KEY",
    "secret_key": "YOUR_STORAGE_SECRET_KEY",
    "region": "us-east-1"
  }
}
```

### google_search · arguments JSON

```json
{
  "query": "MCP protocol",
  "num": 3,
  "gl": "us",
  "hl": "en",
  "mode": "async"
}
```

### youtube_search · arguments JSON

```json
{
  "query": "renewable energy",
  "max_results": 5,
  "filters": {
    "type": "video",
    "duration": "<4",
    "subtitles": true
  }
}
```

### youtube_transcript · arguments JSON

```json
{
  "video_id": "FUfGcZ092b0",
  "language": "en",
  "auto": true,
  "mode": "async"
}
```

### submit_batch · arguments JSON

```json
{
  "queries": [
    {
      "source": "google_search",
      "query": "renewable energy",
      "num": 3
    },
    {
      "source": "youtube_metadata",
      "video_id": "FUfGcZ092b0",
      "include_formats": false
    }
  ]
}
```

### get_job · arguments JSON

```json
{
  "job_id": "job_REPLACE_WITH_RETURNED_ID"
}
```

### get_result · arguments JSON

```json
{
  "result_id": "result_1800000000000_00000000-0000-0000-0000-000000000000",
  "offset": 16000,
  "limit": 16000
}
```

### get_pricing · arguments JSON

```json
{
  "source": "google_search",
  "request_count": 3
}
```

### get_usage · arguments JSON

```json
{
  "source": "youtube_metadata",
  "from": "2026-09-21T00:00:00Z",
  "to": "2026-09-22T00:00:00Z"
}
```

<a id="client-example"></a>

## Проверка с помощью клиента JavaScript

Этот клиент использует проверенный официальный SDK 1.30.0 для подключения через потоковый HTTP и список инструментов без запуска платного запроса. Сохраните его как mcp-check.mjs, установите FLASHDATA_API_KEY в своей среде, затем запустите узел mcp-check.mjs.

### npm

```bash
npm install @modelcontextprotocol/sdk@1.30.0
```

### mcp-check.mjs

```javascript
import { Client } from '@modelcontextprotocol/sdk/client/index.js';
import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js';

const key = process.env.FLASHDATA_API_KEY;
if (!key) throw new Error('Set FLASHDATA_API_KEY first.');
const client = new Client({ name: 'my-app', version: '1.0.0' });
try {
  await client.connect(new StreamableHTTPClientTransport(
    new URL('https://data.flashdata.dev/mcp'),
    { requestInit: { headers: { 'X-API-Key': key } } }
  ));
  console.log((await client.listTools()).tools.map(tool => tool.name));
} finally {
  await client.close();
}
```
