MCP 调用指南
AI 的分布式研究执行层给它 URL 或目标,它自动跨节点抓取、重试、抽取证据、评分置信度,并返回可追溯报告。这里给没有源码的人使用。
一句话产品定义
Toask Grid(拓思执行云)是 AI 的分布式研究执行层。它不是单机 curl,也不是泛泛的任务队列。它让 Codex/Claude 这类 agent 同时使用多台机器,自动跨 China network、Global network、Browser-capable 等 cohort 抓取页面、失败重试、抽取证据、输出可信报告。
第一楔子:可靠的多页面研究。输入一批策略页、商品页、新闻页或文档页;输出带来源、指标、候选分类、风险证据、置信度和执行追溯的研究结果。
30 秒 killer workflow
输入:我要调研 20 个策略页面。
{
"name": "cluster_research_pages",
"arguments": {
"workflow_template": "research_pages",
"urls": ["https://example.com/strategy-a", "https://example.com/strategy-b"],
"timeout_sec": 60,
"submit_token": "<SUBMIT_TOKEN>"
}
}
系统行为:自动分发、跨 cohort 重试、抽取 title/main_content/table/comment/boilerplate 证据、给候选项评分、给研究结果打信心分。
{
"report": {
"headline": "20 pages researched, 20 ok, evidence confidence medium",
"confidence": {"score": 0.82, "level": "high"}
},
"summary": {
"execution_report": {
"headline": "20 URLs, 20 ok, 5 retries, p95 1800ms, 997000 bytes processed",
"recovery": "5 URL(s) recovered by fallback network routing."
}
}
}
report.headline、execution_report、confidence、task_id 和 trace_count。快速开始
公网 MCP 入口:
https://mcp.toask.ai/mcp
最小可用调用只需要管理员在 dashboard 创建的一个 mwsk_... MCP 客户端令牌。读工具和提交工具都使用同一个 Bearer token。
export MCP_TOKEN="<dashboard-issued mwsk token>"
curl -sS https://mcp.toask.ai/mcp \
-H "Authorization: Bearer $MCP_TOKEN" \
-H "Content-Type: application/json" \
-d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"cluster_auth_status","arguments":{}}}'
<...> 都是占位符。认证模型
| Token | 用途 | 放在哪里 | 常见错误 |
|---|---|---|---|
MCP_TOKEN | 访问 /mcp,列工具、读集群、提交任务,并按用户/租户/任务 kind/route 授权 | HTTP Header: Authorization: Bearer mwsk_... | mcp bearer token or dashboard access token required or invalid |
submit_token | 旧客户端兼容字段;新客户端通常不需要 | MCP tool arguments,字段名 submit_token | submit token required or invalid |
DASH_TOKEN | 打开 dashboard 页面 | 访问 /dashboard 后在页面输入 | dashboard token required or invalid |
cluster_auth_status 会告诉你当前 MCP 会话能读、能不能提交、admin gate 是否开启,但不会回显任何 token 值。
客户端配置
Claude Code / Claude Desktop HTTP MCP
claude mcp add --transport http toask-grid https://mcp.toask.ai/mcp \
--header "Authorization: Bearer <MCP_TOKEN>"
通用 HTTP 客户端
所有请求都是一个 JSON-RPC POST,路径固定为 /mcp。
POST /mcp
Authorization: Bearer <MCP_TOKEN>
Content-Type: application/json
原始 JSON-RPC 格式
列出工具
curl -sS https://mcp.toask.ai/mcp \
-H "Authorization: Bearer $MCP_TOKEN" \
-H "Content-Type: application/json" \
-d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'
调用工具
{
"jsonrpc": "2.0",
"id": 2,
"method": "tools/call",
"params": {
"name": "cluster_jobs",
"arguments": {}
}
}
MCP 返回的正文在 result.content[0].text,里面通常是一个 JSON 字符串。
常用工具
| 工具 | 用途 | 是否需要 submit token |
|---|---|---|
cluster_auth_status | 解释当前认证能力,不泄露 secret | 否 |
cluster_agents | 查看 live 节点、版本、能力、sandbox | 否 |
cluster_jobs | 查看当前可运行 job kind 和 route 分布 | 否 |
cluster_fetch_many | 批量 HTTP GET,自动 fallback route 重试,返回摘要和 trace | 通常需要 |
cluster_research_pages | 抓取页面并做通用证据抽取、候选评分、zone 标注 | 通常需要 |
cluster_submit | 提交任意集群任务 | 是 |
cluster_wait | 等待单个 task 完成 | 否 |
cluster_result | 查 task 结果或最近结果 | 否 |
cluster_trace | 查 task/batch 全量执行轨迹 | 否 |
任务模板
不要让用户每次手写复杂 extraction_spec。先传 workflow_template,模板会填充通用关键词、正则和 zone 权重;需要领域判断时再由上层 agent 覆盖。
| 模板 | 适合场景 | 默认关注 |
|---|---|---|
research_pages | 策略页、文档页、论坛长页研究 | 来源、指标、风险、证据密度 |
compare_products | 商品/服务横向比较 | 价格、功能、参数、评价、售后 |
monitor_price | 价格和库存监控 | 金额、折扣、库存状态 |
collect_market_news | 市场新闻采集 | 市场、公司、政策/宏观线索 |
authenticated_fetch | 带权限页面抓取 | 登录状态、权限、错误 |
browser_check | 浏览器可达性/渲染检查 | 加载成功、登录拦截、错误 |
批量抓取:cluster_fetch_many
适合“给我抓一批 URL”。失败时工具会自动换 compatible fallback route 重试一次,不需要用户知道哪个节点失败后该换哪个 route。
curl -sS https://mcp.toask.ai/mcp \
-H "Authorization: Bearer $MCP_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"jsonrpc":"2.0",
"id":10,
"method":"tools/call",
"params":{
"name":"cluster_fetch_many",
"arguments":{
"urls":["https://example.com","https://example.org"],
"text":true,
"max_bytes":200000,
"timeout_sec":45,
"submit_token":"<SUBMIT_TOKEN>"
}
}
}'
结果重点字段:
summary.total/ok/fail/runningsummary.execution_report.headline:人能直接扫一眼的执行报告。summary.by_agent,route_distribution,cohort_distributionsummary.p50_latency_ms/p95_latency_ms,retries,bytes- 每个 result 的
agent,route,network,fallback_route,fallback_network,retry_attempts,recovery,attempts,trace_count
默认展示 cohort 语言:China network、Global network、Browser-capable、Sandbox-capable、High-memory。工程字段如 cn2、ov1、route=global 仍保留给追溯使用。
页面证据抽取:cluster_research_pages
这个工具不是领域分类器,也不做投资判断。它只做“抓取 + 通用 evidence extraction + candidate scoring”。上层 agent 再根据证据决定最终判断。
{
"name": "cluster_research_pages",
"arguments": {
"workflow_template": "research_pages",
"urls": ["https://www.joinquant.com/community/post/detail?..."],
"max_bytes": 500000,
"timeout_sec": 60,
"extraction_spec": {
"keywords": ["年化", "回测", "JoinQuant"],
"categories": {
"多因子": ["多因子", "因子", "alpha"],
"打板弱转强": ["打板", "弱转强", "涨停"]
},
"regexes": {
"percent": "[0-9]+(?:\\.[0-9]+)?%"
},
"zone_weights": {
"title": 5,
"main_content": 3,
"table": 2,
"comment": 1,
"boilerplate": 0.25
}
},
"submit_token": "<SUBMIT_TOKEN>"
}
}
输出语义
title:完整浏览器标题。page_title,author,site:结构化标题字段;作者名默认不参与候选评分。extraction_zones:title,main_content,table,comment,boilerplate。category_candidates:候选项数组,每项有name,score,evidence。confidence:score、level和why,解释为什么这页证据可信或不可信。report:批次级研究报告摘要,适合人读。evidence[].zone和weight:让上层 agent 可以忽略评论区/导航噪声。
不要把 category_candidates[0] 当最终结论。它只是证据候选排序。
提交任意任务:cluster_submit
适合高级调用方。先用 cluster_jobs 看 kind、route 和 schema。
{
"name": "cluster_submit",
"arguments": {
"kind": "http_fetch",
"route": "global",
"payload": {
"url": "https://example.com",
"text": true,
"max_bytes": 100000
},
"submit_token": "<SUBMIT_TOKEN>"
}
}
cluster_submit 只返回 task id。随后用 cluster_wait 或 cluster_result 取结果。
结果追溯
{
"name": "cluster_trace",
"arguments": { "task_id": "t-..." }
}
trace 会给出 submit、started、retry、result 等事件,包含 agent、route、duration、nats delivery、redacted payload/output hash。它用于证明任务不是黑盒操作。
排错
| 现象 | 含义 | 处理 |
|---|---|---|
mcp bearer token required or invalid | MCP bearer 缺失或错误 | 检查 Authorization: Bearer <MCP_TOKEN> |
submit token required or invalid | 提交任务缺少有效 submit token | 让管理员发用户 submit token,或确认服务端 submit token 已配置 |
dashboard token required or invalid | dashboard 页面未登录或 token 错误 | 打开 /dashboard,在登录框输入 Dashboard Token |
no node runs job kind | 当前 live 节点不支持该 kind | 先调 cluster_jobs 查看可用 kind |
| 某 URL 首次失败但最终 ok | fallback route 自动补救成功 | 看 result 的 attempts 和 fallback_route |
恢复解释在 result.recovery:包含首轮失败 route/network、fallback network、恢复 agent 和 future hint,例如“Global network recovered this host,下次类似 URL 优先 global”。
安全约定
| 能力 | 权限边界 |
|---|---|
| Read tools | dashboard 创建的 MCP 客户端令牌 |
| Submit tools | 同一个 MCP 客户端令牌;服务端 submit token 仅用于内部兼容 |
| Dashboard | DASH_TOKEN |
| Admin tools | admin token + 可选 mTLS + audit sink |
| Secrets | 不在 auth status、trace、提交任务 body 中回显 |
- 不要在公开页面、聊天、工单、日志里粘贴真实 token。
- 普通调用方只需要一个 dashboard 创建的 MCP 客户端令牌;
DASH_TOKEN和 admin token 只给管理员。 - 调用工具时只传必要的 payload。含 cookie/header 的字段会被 trace redaction,但调用方仍应最小化提交。
- 管理类工具默认隐藏/禁用;生产环境要求额外 admin token、mTLS 和 audit sink。