远程模式 - 进阶

本文档说明 Dataify MCP 远程模式的服务架构、请求格式、传输方式、配置项与运维细节。

MCP 服务架构

传输方式

Dataify MCP Server 支持以下传输方式，通过启动参数 -transport 指定：

传输方式	参数值	说明	端点路径
STDIO	`stdio`	标准输入输出，由客户端进程管理生命周期	—
HTTP	`http`	Streamable HTTP 协议	`/mcp`
SSE	`sse`	Server-Sent Events 长连接	`/sse` + `/message`
双模式（默认）	`both` 或 `all`	同时提供 HTTP 和 SSE	`/mcp` + `/sse`

默认启动会在同一端口同时提供 HTTP 和 SSE 两种接入方式。

服务端点

端点	用途	说明
`/mcp`	HTTP MCP 入口	Streamable HTTP 协议端点
`/sse`	SSE 连接入口	Server-Sent Events 长连接握手
`/message`	SSE 消息端点	SSE 模式下的消息收发
`/healthz`	存活探针	进程存活即返回 200 OK
`/readyz`	就绪探针	依次 Ping MySQL / ClickHouse / Redis，全部可达返回 200，否则 503

默认配置

以下为服务端默认配置值（可通过 configs/config.yaml 覆盖）：

配置项	默认值	说明
`server.name`	`dataify-task-status-mcp`	服务名称
`server.version`	`1.0.0`	服务版本号
`server.port`	`7780`	监听端口
`server.timeout`	`30s`	请求超时时间
`web_unlocker.base_urls`	`https://webunlocker.dataify.com`	网页解锁接口地址
`web_unlocker.timeout`	`180s`	网页解锁请求超时
`scraper_api.base_urls`	`https://scraperapi.dataify.com`	网页采集 Builder 接口地址
`scraper_api.timeout`	`180s`	网页采集请求超时
`serp_api.base_urls`	`https://scraperapi.dataify.com`	SERP 搜索引擎接口地址
`serp_api.timeout`	`180s`	SERP 请求超时

MCP 服务地址及请求格式

MCP 服务地址

https://mcp.dataify.com/mcp          # HTTP 模式
https://mcp.dataify.com/sse          # SSE 模式

本地开发默认地址：http://localhost:7780/mcp

请求格式

HTTP 模式

https://mcp.dataify.com/mcp?token=<your-api-token>&tools=<tool-list>

SSE 模式

https://mcp.dataify.com/sse?token=<your-api-token>&tools=<tool-list>

SSE 模式使用 Redis 缓存 Session 鉴权信息（TTL 24 小时），首次连接时将 token 和 tools 存入 Redis，后续通过 sessionId 自动恢复鉴权。

⚠️ 客户端兼容性提示：SSE 端点并非所有客户端都支持。例如 Codex 仅支持 HTTP 传输（/mcp），无法使用 SSE 端点；Claude Code、Cursor、VS Code 等客户端均同时支持 HTTP 与 SSE。选择 SSE 模式前请确认所用客户端支持该传输方式。

参数说明

参数	类型	必填	说明
`token`	String	是	Dataify API Token，用于身份认证
`tools`	String	否	逗号分隔的 MCP Tool 名称列表，用于限制可见工具；不传时仅显示免费工具

tools 参数详解

不传 tools：仅展示免费工具，调用非免费工具会返回「当前工具不可用」错误

传入 tools：仅展示已启用的工具或分类，需与账户权限匹配

格式：逗号分隔的工具名，如 google_search,request_web_unlocker,amazon_product

去重：重复的工具名会被自动去重

示例

认证机制

Token 传递方式

Token 通过 URL 查询参数传递，支持两种模式：

直接传参：每次请求携带 ?token=xxx&tools=yyy

SSE Session：SSE 模式下首次连接时传参，后续通过 Redis 缓存的 sessionId 自动恢复（24 小时有效）

工具权限控制

服务端实现了两级权限过滤：

工具列表过滤（filterToolsByAccess）：根据 token 和 tools 参数查询账户可用的工具码，不在白名单中的工具不会暴露给客户端

工具调用守卫（guardToolCallByAccess）：每次实际调用前再次校验工具是否在允许列表中，未授权的调用返回错误

未授权时的错误信息：

当前工具不可用：未传 tools 时仅允许免费工具；传入 tools 时需要匹配已启用的工具或分类

日志配置

日志通过 log 配置节点控制：

配置项	可选值	默认值	说明
`level`	`debug` / `info` / `warn` / `error`	`info`	日志级别；排查上游请求参数时设为 `debug`
`format`	`json` / `text`	`json`	输出格式
`output`	`stdout` / `stderr`	`stdout`	输出目标

日志记录内容包括：

服务启动信息（名称、版本、端口、传输方式）

HTTP/SSE 请求日志（方法、路径、状态码、字节数、耗时、是否有 token、tools 列表）

MCP 工具调用日志（工具名、耗时、是否有错误）

上游请求状态码和耗时

⚠️ debug 级别会记录 SERP 表单字段，但不会输出完整 token 或 Authorization 信息。

CORS 跨域配置

HTTP 和 SSE 端点均支持 CORS 跨域配置：

配置项	默认值	说明
`allowed_origins`	`*`（允许所有来源）	CORS 白名单；未配置时默认允许所有来源

允许的请求头：Content-Type、Mcp-Session-Id、Last-Event-ID
暴露的响应头：Mcp-Session-Id

数据存储依赖

服务启动时会依次检查以下存储后端的连通性（可通过 check_database_on_start: false 跳过）：

存储	用途
MySQL	任务状态数据主库
工具权限 MySQL	工具访问权限校验
ClickHouse	任务统计数据
Redis	SSE Session 鉴权缓存

就绪探针 /readyz 会依次 Ping 以上 4 个存储，任一不可达即返回 503 Service Unavailable。

故障排查

常见问题

连接成功但无法调用工具

请按顺序检查：

API Token 是否有效 — 在 Dataify 控制台确认 Token 未过期

tools 参数是否正确 — 工具名必须与服务端注册名完全匹配（如 google_search，不是 google_serp）

账户是否拥有对应工具权限 — 部分工具需要特定订阅等级

MCP 工具是否已开放 — 联系 Dataify 官方确认工具可用性

健康检查失败（503）

检查以下存储后端是否可达：

MySQL 主库和工具权限库

ClickHouse

Redis（SSE 模式必需）

查看日志中的具体报错信息定位是哪个存储连接失败。

SSE 连接断开

SSE Session 在 Redis 中的 TTL 为 24 小时。如果连接断开后无法恢复：

检查 Redis 是否正常运行

重新发起 SSE 连接（带 token 和 tools 参数）

工具调用超时

各上游接口默认超时时间为 180 秒（网页解锁 / SERP / 网页采集）。如果频繁超时：

检查网络到 scraperapi.dataify.com / webunlocker.dataify.com 的连通性

对于 SERP 搜索，可尝试设置 no_cache=true 跳过缓存层

对于网页解锁，可调整 js_render、block_resources 等参数减少渲染时间

进阶

远程模式 - 进阶#

MCP 服务架构#

传输方式#

服务端点#

默认配置#

MCP 服务地址及请求格式#

MCP 服务地址#

请求格式#

HTTP 模式#

SSE 模式#

参数说明#

tools 参数详解#

示例#

认证机制#

Token 传递方式#

工具权限控制#

日志配置#

CORS 跨域配置#

数据存储依赖#

故障排查#

常见问题#

连接成功但无法调用工具#

健康检查失败（503）#

SSE 连接断开#

工具调用超时#