# MCP 工具与结构

查看 FlashData MCP 的工具参数、默认值、账户读取、任务状态与结果获取方式。

Canonical reference: https://flashdata.dev/zh/docs/mcp

[选择 MCP 客户端并连接](https://flashdata.dev/zh/docs/integrations/mcp-clients/reference.md)

[OAuth, Codex, OpenClaw and API-key access](https://flashdata.dev/zh/docs/guides/agent-access/reference.md)

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

## 传输与认证

托管 MCP 通过以下地址提供 Streamable HTTP 服务。API Key 连接需发送 X-API-Key 请求头；工具访问受来源权限及可用 Credits 限制。

### Streamable HTTP

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

把实际 FlashData API Key 保存在客户端的凭据配置中。不要把它发到对话里或填入工具参数。此处介绍 API Key 连接；OAuth 登录和已验证的 Codex、OpenClaw 配置见智能体访问指南。youtube_download 提供异步媒体下载，需要相应 API Key 权限。

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

## 查询工具

客户端会发现密钥有权限使用的工具。全部 6 个 Google 和 8 个 YouTube 数据工具默认实时执行，也可以设置 mode 为 async。submit_batch 支持这两类数据查询。youtube_download 使用正式 Download API，必填用户 storage，支持异步或 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>

## 工具参数

MCP 查询参数直接放在工具 arguments 对象中，例如 query、num、language 和 mode，不使用 REST API 的 params 包装。单个查询工具由工具名决定 source；submit_batch 的每一项才需要 source。工具不接收 API Key 或 callback_url。以下 JSON 是工具参数对象，可以通过客户端的 callTool({ name, arguments }) 传入。

布尔值使用 true/false，整数使用数字，不能用字符串代替。未列出的字段会被拒绝。14 个数据查询工具的 mode 可选 realtime 或 async，默认 realtime；批量每项不接受 mode。

| 工具 | 必填参数 | 可选参数与默认值 |
| --- | --- | --- |
| youtube_download | video_id, storage | mode 仅支持 async（默认）。download_type：audio_video（默认）/video/audio；video_quality：默认 <=720，可用 best/worst 或 <=、==、>= 加 144/360/480/720/1080/1440/2160/4320；fps：同样的比较符加 1–240。output_format：视频 mp4（默认）/webm/mkv，音频 m4a（默认）/mp3/opus。audio_language：default/original；audio_quality：best/320/256/192/128，仅音频。yt_dlp_format：最多 1024 字符，覆盖画质、帧率和语言选择。纯音频不传 video_quality/fps，纯视频不传 audio_language。storage 必填，结构与正式 API 的 params.storage 相同。start_at/end_at：HH:MM:SS，最多 12 小时，end_at 必须晚于 start_at；upload_metadata：布尔值，默认 false。批量每条下载都必须提供 storage。不接受 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-compatible、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。endpoint 必须可从 Worker 访问。凭据从你的存储配置读取，不要粘贴进聊天或回显。 |
| google_* | query | query：1–2,000 字符。gl：2 字母国家码；hl：1–35 字符语言码；location/tbs：1–200 字符；num/page：1–100 整数；autocorrect：布尔值。省略时按搜索服务行为处理，不保证固定国家、语言或结果数量。 |
| youtube_search | query | query：1–2,000 字符。max_results：1–20，默认 20；filters：筛选对象，省略或 null 表示不筛选。 |
| youtube_search_extended | query | query：1–2,000 字符。max_results：1–700，默认 20；filters：与标准搜索相同。 |
| youtube_metadata | video_id | include_formats 和 include_chapters：布尔值，均默认 true。 |
| youtube_transcript | video_id | 省略 language 时优先 en-orig，再尝试 en，返回单轨。auto=true 时每种语言先尝试对应的 -orig 轨，再尝试原代码；显式 -orig 和 auto=false 保持精确选择。数组会尝试所有 1–10 种请求语言，按顺序返回 tracks 和 errors。auto 默认 true，选择自动字幕。 |
| youtube_captions | video_id | 省略 language 时优先 en-orig，再尝试 en，返回单轨。auto=true 时每种语言先尝试对应的 -orig 轨，再尝试原代码；显式 -orig 和 auto=false 保持精确选择。数组会尝试所有 1–10 种请求语言，按顺序返回 tracks 和 errors。auto 默认 false，选择上传者字幕。 |
| youtube_trainability | video_id | 除 mode 外无可选参数。检查 Creative Commons 许可分类，不代表授予训练权限。 |
| youtube_channel | handle | handle：1–100 字符；video_limit：1–100，默认 20。 |
| youtube_suggestions | query | query：1–2,000 字符；language：默认 en；region：2 字母国家码，默认 US。 |

video_id 必须是 11 字符的 YouTube ID，只含字母、数字、下划线或连字符，不填写完整视频 URL。每个语言代码为 1–35 字符，只含字母、数字或连字符。字幕 auto=true 选择自动字幕，false 选择上传者字幕，不会自动在两类字幕间回退。请求语言数组时，即使任务成功也请检查 errors。

### YouTube 搜索筛选

filters.type：video/channel/playlist/movie；upload_date：today/last_hour/this_week/this_month/this_year；duration：<4、4-20 或 >20；sort_by：rating/relevance/view_count/upload_date。以下字段均为布尔值，true 表示要求该特性：360、3d、4k、creative_commons、hd、hdr、live、location、purchased、subtitles、vr180。

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

## 账户查询（免费）

get_balance 查询账户余额；get_pricing 查询套餐单价和调用成本预估；get_limits 查询套餐上限和当前排队数；get_usage 汇总最近 7 天用量（最多查询 31 天）。用量覆盖当前 Key 授权来源在整个账户的请求，统计可能有延迟。

get_balance 和 get_limits 使用空参数 {}。get_pricing 的 source 可选，省略时返回 Key 授权的 MCP 查询来源价格；request_count 为 1–100000 的整数，默认 1，表示请求次数，分页和批量每项分别算一次。get_usage 的 source 可选，省略时汇总 Key 授权的全部来源，也可读取 youtube_download 的用量。下载价格返回 creditsPerTb（1 TB = 10^12 字节），按实际上传字节结算并预留额度；request_count 不适用于下载，estimatedCredits 为 null。

get_usage 的 from/to 使用 UTC ISO 时间，例如 2026-09-21T00:00:00Z，可含 1–3 位小数秒。from 含边界，to 不含边界，向下对齐分钟；默认 7 天、最多 31 天。只传 from 时，to 为 7 天后；只传 to 时，from 为 7 天前。具体返回窗口以响应中的 from/to 为准。

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

## 任务与大结果

异步请求返回任务 id，使用 get_job 的 job_id 参数读取 job.status；任务完成后，output 包含原始查询响应；下载返回上传结果，其中 output.results[0].file_url 指向用户存储，另有 file_size、downloaded_bytes、md5 等字段。私有文件需使用用户存储自身的认证方式访问。JSON 结果保留 24 小时；媒体文件的保留与访问策略由用户存储决定。submit_batch 接受至少一条 Google 或 YouTube 查询（含下载），每项包含 source 和该来源的平铺参数。每项分别计费，批量数量与待处理任务上限由套餐决定。读取任务不会再次扣费。MCP 不提供文件式 Bulk 工具。

将示例中的 job_id/result_id/offset 替换为实际响应中的值，不要重新提交查询来获取下一段结果。

较大响应返回 JSON 文本分段、result_id 和 next_offset。使用同一把 Key 调用 get_result，必填 result_id；offset 为非负整数，默认 0，续读时填写上次的 next_offset；limit 为 1–16000 的整数，默认 16000，单位是 UTF-16 code units，不是字节或结果条数。按偏移拼接全部 chunk 后解析 JSON，next_offset=null 表示结束。缓存有效期 10 分钟，每把 Key 最多保留 4 个大结果，可能提前被淘汰。读取分段不重复查询或扣费。

[处理 ID 文件？使用 Bulk HTTP API](https://flashdata.dev/zh/docs/reference/bulk-processing/reference.md)

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

## 计费与错误

查询按现有套餐单价扣除 Credits，MCP 不额外扣费。业务错误使用 isError 标记，并保留上游 HTTP 状态与请求 ID。余额不足时先补充额度；权限不足时检查密钥权限。

查询超时或连接中断不代表任务未执行。遇到 query_outcome_unknown，先在控制台的请求记录中检查，再决定是否重提。不要自动重试付费提交；读取已有任务或分段可以重试。单个上游响应最大 4 MiB，建议限制搜索数量；超出限制也可能已扣费。

[底层 HTTP 状态码](https://flashdata.dev/zh/docs/errors/reference.md#status-codes) · [重试规则](https://flashdata.dev/zh/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，通过 Streamable HTTP 连接并列出工具，不执行付费查询。把代码保存为 mcp-check.mjs，在环境中配置 FLASHDATA_API_KEY 后运行 node 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();
}
```
