Selda

Selda MCP

将 AI 客户端连接到 Selda 工作区。

其他产品卖给你一个工具。Selda 为你打造销售引擎：它会捕捉值得联系的时机，研究每家公司，用客户的语言撰写消息，从你自己的收件箱发送，并把回复带回给你。每次发送都由人工审批。本仓库是这台引擎的机器可读文档，供你通过 Model Context Protocol 或纯 HTTP 从应用外部驱动它。

所有套餐都包含 MCP 和 API，也包括免费套餐。 连接客户端无需升级到更高套餐——请参阅密钥、范围与隔离，了解免费工作区中的密钥可以执行哪些操作。

叙述性文档位于 docs.selda.ai/reference/mcp。 如果两者内容不一致，请以此处所述的实时功能清单为准。

你可以用它做什么

你想做什么	方法
从 AI 客户端读取工作区、潜在客户、营销活动和对话	连接托管服务，然后直接提问
将已完成的研究推送到 Selda，让它根据你的材料撰写内容	使用带有 analysis 字段的 selda_add_lead，或上传文件并导入
根据简介运行完整流程，并读取生成的草稿	使用 selda_run_pipeline，然后轮询 selda_get_run_status
收到回复时立即获取，而不是轮询	为 reply.received 注册出站 Webhook
有新咨询时，在任何人查看前先回复	使用带有 autoAdvance 的 selda_ingest_event，然后监听 draft.ready
在消息中添加图片，每个潜在客户使用不同图片	在 selda_add_lead / selda_add_leads / selda_ingest_event 中使用 mediaImageUrl，并设置 mediaLinkUrl 使其可点击
随消息发送文件，或随营销活动中的每条消息发送文件	使用 selda_upload_file，然后通过 leadId 或 runId 调用 selda_attach_files
清理试用安装遗留的行	使用 selda_delete_lead；若有重复项，则使用 selda_merge_leads

我们特意不让它做的事

这里没有任何功能会发送外联消息。 脚本可以创建营销活动，直到生成消息草稿为止。 发送操作由人工在 Selda 应用中执行。没有任何函数可以启动营销活动的发送，也没有任何标志可以关闭这项限制。

这并非我们打算移除的限制，而是产品的核心理念：Selda 提出建议，人来做决定。

连接

OAuth，推荐用于 Claude.ai、ChatGPT 和 Cursor

将其添加为自定义连接器：

https://mcp.selda.ai/api/mcp

该服务声明支持 OAuth，因此客户端会引导你登录并选择工作区。 无需粘贴任何内容。

静态密钥，适用于 Claude Code、脚本和 CI

在 Selda 应用的 Settings → Connections → MCP server 下创建密钥。完整密钥只会显示一次。

claude mcp add --transport http selda https://mcp.selda.ai/api/mcp \
  --header "Authorization: Bearer $SELDA_API_KEY"

任何其他读取配置文件的 MCP 客户端也使用相同的 URL 和请求头。

密钥、范围与隔离

密钥格式为 sk_live_…（正式环境）或 sk_test_…（沙盒环境）。密钥只会以 SHA-256 哈希的形式存储，因此密钥一旦丢失，就只能撤销，无法找回。

范围	授予权限
read	读取操作
write	写入操作
pipeline	流水线和引擎操作，这些操作会消耗额度

每次调用都绑定到密钥所属的组织。服务器会根据已验证的密钥注入组织 ID，并忽略请求正文中的 orgId。一个组织的密钥无法访问另一个组织的数据。

所有套餐都可以连接，包括免费套餐。 创建密钥不受套餐等级或发票限制。处于测试模式的工作区始终生成 sk_test_ 密钥；获准使用正式环境的工作区始终生成 sk_live_ 密钥。前缀仅表明环境，本身不授予任何权限——每项权限检查都会读取已存储的环境，并在每次请求时重新解析工作区的正式环境权限。

因此，在免费工作区中，你会获得一个测试密钥，可以访问全部功能，但少数需要花费资金或解析真实人员的功能除外。这足以让你在一切投入实际使用之前，完成整个集成。能力清单是判断给定密钥可以调用哪些功能的依据。

底层 HTTP API

MCP 工具是 HTTP API 的精选前端，你也可以直接调用该 API。

基础 URL 为 https://api.selda.ai。

端点	方法	用途
/mcp/query	POST	读取
/mcp/mutate	POST	写入
/mcp/run	POST	流水线和引擎操作
/mcp/material/upload	POST	上传原始文件字节，返回存储 ID
/mcp/capabilities	GET	获取能力清单，无需密钥

以上每个端点也都支持 /v1/ 别名——/v1/mcp/query、/v1/mcp/mutate、 /v1/mcp/run、/v1/mcp/material/upload、/v1/mcp/capabilities——并指向同一个处理程序。 不带版本号的路径会一直保留，不会失效；/v1/ 是任何行为变更将出现的分界点，因此对于长期使用的代码，建议优先使用它。

请求正文始终为 { "fn": "...", "args": { ... } }。成功响应为 { "value": … }；失败响应为 { "error": { "type", "code", "message", "request_id" } }，并返回非 200 状态码。

每项操作也都有对应的 URL，如果你的客户端需要这种形式：GET /v1/leads、 POST /v1/leads、POST /v1/runs/{runId}/confirm-companies，以及另外六十多个端点，并提供 OpenAPI 3.1 文档。它们使用相同的分发器、相同的密钥检查、相同的范围检查和相同的拒绝规则，因此无论使用哪种形式，都无法访问另一种形式所拒绝的内容。该接口的文档见 Selda-rest-api。编写代码时请使用它；连接 AI 客户端时请使用本仓库。

请从清单中获取基础 URL 和当前功能列表，而不要将二者硬编码。参见 examples/，其中的客户端正是这样做的，代码大约只有 40 行。

基于已有研究撰写消息

你可能已经在别处为每位潜在客户整理了研究资料。可以通过两种方式导入这些资料，这两种方式都能让 Selda 根据你提供的材料撰写内容，而不是从头开始抓取。

已研究过的一家公司：

curl -X POST "$SELDA_API_BASE/mcp/mutate" \
  -H "Authorization: Bearer $SELDA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"fn":"leads.add","args":{
        "projectId":"<workspace id>",
        "company":"Filterit Oy",
        "email":"[email protected]",
        "analysis":"They run three production lines and posted about downtime in March..."
      }}'

一个包含文件的文件夹，每家公司对应一个文件夹： 上传每个文件时添加 X-Selda-Path 标头，然后导入返回的存储 ID。路径中的首个文件夹用于让 Selda 将文件映射到公司，因此 boreo/filterit/analyysi.pdf 归属于 Filterit。

导入材料会创建营销活动和公司列表，仅此而已。向 Selda 提供材料，表示允许它读取材料，而不是允许它运行营销活动。脚本可以通过 autoAdvance 参数逐个授权后续阶段，即便如此，它也无法发送内容。

仓库内容

路径	内容
schemas/capabilities.json	从实时服务生成的所有函数
examples/	无依赖的最小可运行客户端
skills/	可加载的技能，教会 AI 客户端如何妥善使用 Selda
CHANGELOG.md	工具接口的变更，避免集成在不知情的情况下失效

schemas/capabilities.json 根据 GET /mcp/capabilities 生成，而后者本身源自各端点所使用的同一组分发表。它不会描述不存在的函数，也不会遗漏实际存在的函数。每个条目都包含其 fn、端点、作用域、单行摘要、封装该函数的 MCP 工具、沙盒密钥是否可以调用、不能调用时的原因，以及所需的任何额外授权。

如果文件与实时端点不一致，以端点为准，本仓库已过时。对于任何长期运行的内容，请自行获取该文件。

沙盒密钥可以做什么，不能做什么

在清单于 30.8.2026 发布的 72 个函数中，65 个允许沙盒密钥调用，7 个不允许。这些数字会随接口变化而变动，因此请从 GET /mcp/capabilities 获取，而不要依赖本段中的数字——清单才是权威来源，这里列出的数字只是一个快照。

界限并非“读取与写入”之分。沙盒密钥可以读取整个工作区，也可以推送你自己的数据：添加基于你自己的研究获取的潜在客户、写入 Brain、上传资料、导入资料，以及基于资料起草内容。这就是产品在测试模式下的完整功能，也是让你在付费前打造出值得付费之物的方式。

沙盒密钥不能做的是让引擎生成新的联系人数据，或联系真实的人：

函数	收费原因
company.lookup	通过付费数据提供商查找真实人员
leads.enrich、leads.enrichBatch	同上，按潜在客户计费
engine.start	发现：网页搜索、爬取、按潜在客户计费
connectors.sync	从外部来源拉取并丰富数据
runs.confirmCompanies	确认某次运行的公司列表，从而启动付费工作
runs.startFromLeads	为你推送的每位潜在客户撰写一条消息
material.import 搭配 autoAdvance	授权会让该次运行继续进行联系人查找

这些限制问的是由谁付费，而不是你持有哪种前缀的密钥。 如果某个沙盒密钥属于已在套餐中启用 API 且已付清账单的工作区，就可以调用上表中的所有函数，并使用该工作区自己的额度。拒绝的对象是用脚本把 Selda 当作联系人数据 API、却让 Selda 承担费用的免费账户，而不是在沙盒中工作的付费客户。material.import 是唯一一个取决于参数而非函数本身的条目，因此它在清单中报告 sandboxAllowed: true，只有传入 autoAdvance 时才会拒绝调用。

直到 20.8.2026，这张表中还列有 messages.send。任何分发表中都不存在此函数，也没有计划添加它——有效密钥可以调用上文所述会产生费用或访问数据提供商的函数，但不能调用会联系收件人的函数。我们在此更正这条信息，而不是悄悄删掉，因为读过它的人可能已据此作出计划。

被拒绝的调用会返回 403，其中包含可供你编写分支逻辑的 code，以及可展示给用户的一句话。创建工作区不在这两类操作之列：它是在 Selda 应用中完成的，而且任何密钥都没有可执行此操作的函数。

支持

如有疑问，或需要尚不存在的工具，请访问：docs.selda.ai/support。

采用 MIT 许可证。本仓库包含文档、示例和技能，不包含 Selda 的源代码。