use-sapiom

Sapiom

通过一个 MCP 服务提供 97 种云服务工具。抓取、计算、存储、搜索、生成——按使用量付费，无需供应商账号。

快速设置 — MCP 服务（推荐）

# Claude Code CLI
claude mcp add sapiom --transport http https://api.sapiom.ai/v1/mcp

{
  "mcpServers": {
    "sapiom": {
      "type": "http",
      "url": "https://api.sapiom.ai/v1/mcp"
    }
  }
}

系统会自动使用浏览器身份验证。如需改用 API 密钥，请添加 --header "Authorization:Bearer YOUR_KEY" 或设置 headers 字段。请前往 https://app.sapiom.ai/settings 获取密钥。

适用场景

• 抓取并提取 网页内容、爬取网站、截取屏幕截图
• 在云沙箱中运行代码（Node、Python、Go、Rust），并进行文件 I/O 和进程管理
• 存储数据到 Redis、Vector DB、Search Index 或临时 Postgres
• 使用 Linkup（快速）或 You.com（全面）搜索网络
• 生成媒体——图像（Fal.ai）、语音（ElevenLabs）、音效
• 通过队列、计划任务和发布/订阅发送消息

正在构建 Agent？请使用 sapiom-agent-builder。只是要部署代码？请使用 sapiom-deploy。

可用工具

入门（2）

工具	描述
sapiom_status	检查 MCP 会话身份验证和租户上下文
tool_discover	按关键词查找合适的工具（免费）

抓取与浏览器（9）— 详情

工具	描述
sapiom_fetch	从 URL 获取干净的主要内容，并以 Markdown 格式返回
sapiom_screenshot	截取网页屏幕截图（PNG URL）
sapiom_scrape	使用格式选项和选择器进行高级抓取
sapiom_crawl	爬取整个网站（异步，返回任务 ID）
sapiom_crawl_status	检查爬取任务状态并获取结果
sapiom_map	发现网站上的所有 URL（快速站点地图）
sapiom_extract	使用提示词和架构提取结构化数据
sapiom_extract_status	检查提取任务状态并获取结果
sapiom_site_search	搜索特定网站中的内容

计算（31）— 详情

工具	描述
sapiom_run	在云端运行代码片段（Node/Python/Go/Rust）
sapiom_run_list	列出最近的代码运行记录
sapiom_run_get	按 ID 获取运行结果
sapiom_sandbox_create	创建持久云沙箱
sapiom_sandbox_list	列出活动沙箱
sapiom_sandbox_get	获取沙箱详情
sapiom_sandbox_delete	删除沙箱
sapiom_sandbox_extend	延长沙箱生命周期
sapiom_sandbox_exec	在沙箱中执行命令
sapiom_sandbox_deploy	将沙箱部署为持久服务
sapiom_sandbox_write_file	向沙箱写入文件
sapiom_sandbox_read_file	读取沙箱中的文件
sapiom_sandbox_list_files	列出沙箱目录中的文件
sapiom_sandbox_delete_file	删除沙箱中的文件
sapiom_sandbox_process_logs	获取进程 stdout/stderr 日志
sapiom_sandbox_process_list	列出沙箱中正在运行的进程
sapiom_sandbox_process_get	按 PID 获取进程详情
sapiom_sandbox_process_stop	正常停止进程
sapiom_sandbox_process_kill	强制终止进程
sapiom_sandbox_preview_create	为端口创建公开预览 URL
sapiom_sandbox_preview_list	列出活动预览 URL
sapiom_sandbox_preview_delete	删除预览 URL
sapiom_sandbox_ports	列出沙箱中的开放端口
sapiom_job_deploy	部署计划任务/触发任务
sapiom_job_list	列出已部署的任务
sapiom_job_get	获取任务详情
sapiom_job_update	更新任务配置
sapiom_job_delete	删除任务
sapiom_job_trigger	手动触发任务执行
sapiom_job_list_executions	列出任务执行历史
sapiom_job_get_execution	按 ID 获取执行结果

数据（23）— 详情

工具	描述
sapiom_redis_create	创建无服务器 Redis 数据库
sapiom_redis_create_fixed	创建固定大小的 Redis 数据库
sapiom_redis_list	列出 Redis 数据库
sapiom_redis_delete	删除 Redis 数据库
sapiom_redis_update	重命名 Redis 数据库
sapiom_redis_command	执行任意 Redis 命令
sapiom_vector_create	创建向量索引
sapiom_vector_list	列出向量索引
sapiom_vector_delete	删除向量索引
sapiom_vector_update	更新向量索引设置
sapiom_vector_upsert	插入或更新带元数据的向量
sapiom_vector_query	根据相似度查询向量
sapiom_searchindex_create	创建全文搜索索引
sapiom_searchindex_list	列出搜索索引
sapiom_searchindex_delete	删除搜索索引
sapiom_searchindex_update	更新搜索索引架构
sapiom_searchindex_upsert	将文档插入或更新到搜索索引
sapiom_searchindex_query	查询搜索索引
sapiom_database_create	配置临时 Neon Postgres 数据库
sapiom_database_price	获取 Postgres 价格估算（免费）
sapiom_database_list	列出活跃的 Postgres 数据库
sapiom_database_get	获取 Postgres 数据库详情和连接 URI
sapiom_database_delete	删除 Postgres 数据库

消息传递（16）— 详情

工具	描述
sapiom_message_publish	向 URL 端点发布消息
sapiom_message_enqueue	将消息加入指定队列
sapiom_message_batch	在一次调用中发送多条消息
sapiom_message_get	获取消息投递状态
sapiom_message_cancel	取消待处理的消息
sapiom_schedule_create	创建定期计划（cron）
sapiom_schedule_list	列出计划
sapiom_schedule_get	获取计划详情
sapiom_schedule_delete	删除计划
sapiom_schedule_pause	暂停计划
sapiom_schedule_resume	恢复已暂停的计划
sapiom_queue_list	列出消息队列
sapiom_queue_get	获取队列详情
sapiom_queue_delete	删除队列
sapiom_queue_pause	暂停队列
sapiom_queue_resume	恢复已暂停的队列

搜索（2）— 详情

工具	描述
sapiom_search	通过 Linkup 进行网页搜索——生成式 AI 综合答案并附来源
sapiom_deep_search	通过 You.com 进行网页搜索——格式化的网页和新闻结果

AI 模型（2）— 详情

工具	描述
sapiom_chat	通过 OpenRouter 向任意 LLM 发送提示词
sapiom_list_models	列出可用的 LLM 模型和定价

音频（3）— 详情

工具	描述
sapiom_text_to_speech	将文本转换为语音（ElevenLabs）
sapiom_sound_effects	根据描述生成音效
sapiom_list_voices	列出可用的 ElevenLabs 语音（免费）

图像（1）— 详情

工具	描述
sapiom_generate_image	根据文本提示词生成图像（Fal.ai FLUX）

验证（2）— 详情

工具	描述
sapiom_verify_send	通过 SMS 发送验证码
sapiom_verify_check	验证 6 位验证码

治理（6）— 详情

工具	描述
sapiom_create_agent	注册具名 Agent 以便跟踪
sapiom_list_agents	列出已注册的 Agent
sapiom_create_spending_rule	创建支出／使用限额
sapiom_list_spending_rules	列出支出规则
sapiom_create_transaction_api_key	创建新的 API 密钥
sapiom_authenticate	获取身份验证流程说明

使用示例

1. 研究主题

sapiom_search（快速回答）→ sapiom_deep_search（更多结果）→ sapiom_fetch（阅读完整文章）→ sapiom_chat（总结发现）

2. 监控页面变更

sapiom_scrape（获取内容）→ sapiom_redis_command（存储哈希值，并与之前的值比较）→ sapiom_message_publish（变更时发出提醒）→ sapiom_schedule_create（每小时运行一次）

3. 构建知识库

sapiom_crawl（抓取文档站点）→ sapiom_crawl_status（获取页面）→ sapiom_vector_upsert（存储嵌入向量）→ sapiom_vector_query（语义搜索）

4. 运行和部署代码

sapiom_run（测试代码片段）→ sapiom_sandbox_create（创建持久环境）→ sapiom_sandbox_exec（迭代）→ sapiom_job_deploy（安排在生产环境中运行）

5. 生成媒体

sapiom_generate_image（创建视觉素材）+ sapiom_text_to_speech（旁白）+ sapiom_sound_effects（背景音频）

提示

• tool_discover 可通过关键词找到合适的工具——它免费，拿不准时就用它
• 调用网关时传入 agentName，以便按 Agent 跟踪支出
• sapiom_search（Linkup）= 快速 AI 答案；sapiom_deep_search（You.com）= 更多原始结果
• 使用资源前先创建：sapiom_redis_create、sapiom_vector_create、sapiom_database_create
• 部署自主 Agent 前，通过 sapiom_create_spending_rule 设置支出规则
• sapiom_database_price 免费——创建 Postgres 数据库前务必先检查费用

SDK 访问（直接 HTTP）

如需不通过 MCP 直接进行 HTTP 调用，请使用 SDK：

npm install @sapiom/fetch
# or: npm install @sapiom/axios axios

const { createFetch } = require("@sapiom/fetch");
const safeFetch = createFetch({ apiKey: process.env.SAPIOM_API_KEY });

const res = await safeFetch("https://linkup.services.sapiom.ai/v1/search", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ q: "quantum computing", depth: "standard", outputType: "sourcedAnswer" }),
});

Python/curl：使用带有 X-402-Payment 标头的标准 HTTP——网关 URL 请参阅参考文件。

故障排除

问题	原因	解决方法
402 Payment Required	余额不足或触发了支出规则	在 app.sapiom.ai 充值，或检查 sapiom_list_spending_rules
MCP 连接被拒绝	URL 错误或身份验证问题	确认 URL 为 https://api.sapiom.ai/v1/mcp；尝试浏览器身份验证或检查 API 密钥
tool_discover 未返回结果	查询过于宽泛	使用具体关键词：“scrape”、“redis”、“image”、“search”
抓取结果为空	使用 JS 渲染的页面需要等待	使用 sapiom_scrape 并设置 waitFor: 3000，而不是 sapiom_fetch
“未找到资源”	尚未创建资源就使用了数据工具	先创建：sapiom_redis_create、sapiom_vector_create 等
缺少数据库 URI	数据库仍在创建中	等待几秒，然后运行 sapiom_database_get 检查状态

参考资料

文件	领域	工具
scraping.md	Firecrawl + Anchor Browser	9
compute.md	沙盒、任务、运行	31
data.md	Redis、向量、搜索、Postgres	23
messaging.md	QStash 消息、计划、队列	16
search.md	Linkup + You.com	2
ai-models.md	OpenRouter 聊天 + 模型	2
audio.md	ElevenLabs TTS + SFX	3
images.md	Fal.ai 图像生成	1
verify.md	Prelude 电话验证	2
governance.md	Agent、规则、API 密钥	6

完整文档：https://docs.sapiom.ai（在任意 URL 后添加 .md 可获取原始 Markdown）