帮助中心/MCP 调用指南

MCP 调用指南

接入文档最后更新:2026-07-23预计阅读:12 分钟

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."
    }
  }
}
AI 看完整 JSON;人看 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 写进聊天、issue、日志或截图。指南里的 <...> 都是占位符。

认证模型

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_tokensubmit 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/running
  • summary.execution_report.headline:人能直接扫一眼的执行报告。
  • summary.by_agent, route_distribution, cohort_distribution
  • summary.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 invalidMCP bearer 缺失或错误检查 Authorization: Bearer <MCP_TOKEN>
submit token required or invalid提交任务缺少有效 submit token让管理员发用户 submit token,或确认服务端 submit token 已配置
dashboard token required or invaliddashboard 页面未登录或 token 错误打开 /dashboard,在登录框输入 Dashboard Token
no node runs job kind当前 live 节点不支持该 kind先调 cluster_jobs 查看可用 kind
某 URL 首次失败但最终 okfallback route 自动补救成功看 result 的 attempts 和 fallback_route

恢复解释在 result.recovery:包含首轮失败 route/network、fallback network、恢复 agent 和 future hint,例如“Global network recovered this host,下次类似 URL 优先 global”。

安全约定

能力权限边界
Read toolsdashboard 创建的 MCP 客户端令牌
Submit tools同一个 MCP 客户端令牌;服务端 submit token 仅用于内部兼容
DashboardDASH_TOKEN
Admin toolsadmin 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。