MCP 工具服务
Agent 能干的每一件事都从一个 MCP server 进来:五个 FewBox 自建的服务,加上您自己登记的任何 第三方 server。这一页讲它们各自给什么、怎么登记、怎么计价。
← 文档索引
先说清楚:这里没有「市场」
没有服务发现,也没有一键安装。thia-agent 启动时读 agentic.yaml 的 mcp.servers[],
逐条连上去,把连接成功的 server 报上来的工具塞进模型的工具表。由此有三条结论:
- 服务装好了不等于能用——必须在 YAML 里登记一条。
- 工具名是契约,
id不是。 运行时按工具名找 server(心跳抓 RSS 用的是findServerForTool('fetch_feed')),所以id随便起,改名工具就是破坏兼容。 - 登记了但服务没起,只影响那一条(日志里有连接失败行),其余 server 照常工作。
五个自建服务
| 服务 | 工具 | 干什么 | 外部凭据 |
|---|---|---|---|
mcp-vision |
generate_image · edit_image · blending_image |
文生图、单图改图、多图混合(Seedream / Gemini) | 至少一套模型 key |
mcp-perception |
perceive_images · compare_framing |
看图说话;量一张改写后的图有没有丢原取景 | Ark key |
mcp-motion |
generate_video |
文 / 图 / 参考素材生视频 | Ark key |
mcp-fetch |
fetch_url · fetch_feed |
抓网页;读 RSS/Atom 并按条目 id 判新旧 | 无 |
mcp-analysis |
list_databases · run_sql |
只读 SQL:先列可查的库,再查 | 数据库连接串 |
端口与探针见 Service 与端口;环境变量与部署清单见逐服务手动部署的 mcp-* 一节。
每个工具的一句话
generate_image— 文生图。按模型能力决定一次一张还是批量出同主题的一组。edit_image— 单图改写:给一张参考图加指令,输出改过的图。blending_image— 2 张以上参考图混合,上限由模型决定(现有模型 10–14)。perceive_images— 把一个或多张图交给视觉模型,加一句 prompt,拿回描述/分析。compare_framing— 不走视觉模型:特征匹配算两张图的相机位移与缩放,返回stable/drift/undetermined,约一秒。适合确认「只换了家具、没动机位」这类改写。generate_video— 文生视频、首帧/首尾帧生视频;多模态模型还能吃参考图/视频/音频。 调用会一直等到生成结束。fetch_url— 抓一个公网 URL 并转成可读文本(format: raw保留原文)。fetch_feed— 读 RSS/Atom,按条目返回。判新旧请用条目 id,不要用标题—— 标题被人改过一次就会再报一遍。list_databases/run_sql— 先列库拿id,再对那个库跑一条只读 SELECT。 连接本身是只读的,写语句会被拒。
怎么登记
五个服务都是 HTTP 形态(镜像里设了 MCP_TRANSPORT=http,只暴露 POST /mcp),所以地址
要带 /mcp:
mcp:
resilience: # 全局默认,每条 server 可覆盖
callTimeoutMs: 300000 # 出图/出视频是长任务,默认 30s 不够
retry: { maxRetries: 3 }
servers:
- id: 'fewbox-remote-vision'
name: 'FewBox Remote Vision'
enabled: true
transport:
type: 'streamable-http'
url: '${VISION_ENDPOINT}' # http://mcp-vision/mcp
pricing: # 见下一节;不写 = 每次 0 美元
kind: image
models:
<模型名>: { perUnit: { metric: imageCount, rate: 0.035 } }
resilience:
callTimeoutMs: 300000 # 覆盖上面的全局值也可以写成一样
三种 transport:
type |
必填字段 | 什么时候用 |
|---|---|---|
streamable-http |
url(可选 headers) |
集群内的独立服务。五个 mcp-* 都是这一种 |
sse |
url(可选 headers) |
只支持旧 SSE 协议的第三方 server |
stdio |
command(可选 args / env / cwd) |
本地开发;server 作为 agent 的子进程跑 |
⚠️ 集群里优先用
streamable-http。stdio的 server 是 agent Pod 里的子进程,npx -y每次冷启动都要能下载包——Pod 得能出网、有可写临时目录。装得上不代表每次都起得来。
⚠️ 仓库里的出厂
agentic.yaml只登记了 vision / motion / perception / analysis 四条, 没有fetch。 装了mcp-fetch必须自己补一条(工具名fetch_url/fetch_feed), 否则带抓取来源的例行任务启动时打一条Routine runtime fetch NOT available,然后每轮退回模型轮。
加一个第三方 server
同一个 servers[],形状不变:
- id: 'tavily'
name: 'Tavily Search'
transport:
type: 'streamable-http'
url: 'https://<第三方地址>/mcp'
headers: { Authorization: 'Bearer ${TAVILY_API_KEY}' }
pricing: { pricePerCall: 0.008 } # 每次搜索的对外报价
计价规则
价格不在服务里,在这份 YAML 里。服务只在结果的 _meta["com.fewbox/usage"] 里报用量
(张数、token 数),agent 拿这个用量套 YAML 的规则算钱。三选一:
| 模式 | 写法 | 用在哪 |
|---|---|---|
| 每次固定 | pricePerCall: 0.008 |
搜索、抓取这类一次一价 |
| 按量 | perUnit: { metric: imageCount, rate: 0.035 } + 可选 multipliers |
图片按张、视频按 token |
| 按 token | tokens: { inputTokenPricePerMillion, outputTokenPricePerMillion } |
视觉模型回答这类 |
- 一个 server 服务多个模型时(vision 就是),用
models:按模型名分别写;没有模型的工具 (如compare_framing)用tools:按工具名写。 - 匹配不上就是 0,并在记录里标
unpriced。这是故意的:新模型不会悄悄套用别的模型的价。 免费的工具也建议写成{ pricePerCall: 0 },好让「免费」和「忘了配」区分开。 - 写了
models/tools就不能再在顶层写价格,配置校验会直接拒(价格归属有歧义)。
计价的单位是美元;用户的扣费按 billing.creditCostUsd 换算成积分。
角色与心跳
两个字段管「谁能用」和「什么时候能用」,都写在 server 条目上:
requiredRoles: ['ADMIN'] # 只有 ADMIN 角色的会话能看到/调用;不写 = 人人可用
availableInRoutines: false # 心跳里不投放这个 server 的工具
requiredRoles是 fail-closed:会话的角色一个都不命中,整个 server 的工具就从工具表里摘掉。availableInRoutines: false通常给两类:很贵的(出图、出视频——没人看着不该自己跑)、 心跳用不上的(每轮都是新会话,白付工具定义的 token)。
mcp-analysis 出厂就是这么配的——只读 SQL 只给管理员,且心跳永不自动跑。
不登记会怎样
| 症状 | 原因 |
|---|---|
| 模型完全不知道有这个工具 | 没登记、enabled: false,或 URL 连不上(工具表只取自连接成功的 server) |
| 例行任务每轮都退回模型轮 | fetch_feed 不在任何已登记的 server 上 |
| 普通用户看不到某个工具 | requiredRoles 生效;这也是确认权限配对了的最快办法 |
| 出图/出视频总超时 | resilience.callTimeoutMs 用了默认 30s,长任务要 300s |
登记完从 thia-web 发一条对话,日志里应看到每个 server 逐个连接成功——这是唯一能证明
「工具真的到了模型手里」的检查;探针绿、页面打得开都不算。