REST 接口来源

接口来源如何工作#

接口来源把一个 HTTP 服务变成 Agent 可以直接调用的工具。只要服务有接口，配好基地址和凭据就能接入，不需要对方额外提供 MCP 服务。

配置完成后，工作台会生成一个通用的 HTTP 请求工具：Agent 自己决定方法、路径、查询参数和请求体，认证信息由工作台统一附带，你不用在每次对话里重复交代。

baseUrl 决定工具请求路径的拼接起点；它不是文件或网络沙箱。访问范围还取决于服务方账号权限、令牌 scope 和来源权限规则。

配置#

接口来源通过来源目录里的 config.json 声明。type 固定为 api，其余字段决定请求打向哪里、用什么方式认证，以及如何校验连接。

来源目录里的其余文件与接口来源同样配合使用：说明文件用来告诉 Agent 这个接口该怎么调，权限文件用来限定只读模式下允许的请求方法与路径。

认证方式#

认证方式决定凭据以什么形式出现在请求里。绝大多数现代服务使用 bearer 令牌，老接口多用自定义请求头或查询参数，也有服务只认用户名加口令。

需要同时提供多组凭据时，用多请求头方式：每个名称会对应一个独立的输入项，所有请求头会一起带进每一次请求。

通用 OAuth：自动发现与显式端点#

对 provider 不是 google、microsoft 或 slack 的 API，设置 api.authType: oauth。没有 api.oauth 时，运行时从 baseUrl 尝试 RFC 9728 受保护资源元数据、RFC 8414 授权服务元数据及动态客户端注册；这要求服务实际发布这些能力。

服务不支持发现时，在 api.oauth 明确指定授权端点、令牌端点、客户端 ID 和范围。下面是 GitHub 自建 OAuth App 的完整示例；Client ID/Secret 必须替换为你自己的注册值，并选择所需的最小 scope。

1. 在服务商后台注册你自己的 OAuth 应用。桌面来源授权使用 http://localhost:{本次端口}/callback，监听从 6477 起选择空闲端口。注册规则必须允许该回调；不要使用 Craft 托管地址或假定 8914 固定可用。
2. 保存配置后，请 Agent 调用 source_oauth_trigger({"sourceSlug":"github-oauth"})，在浏览器核对账号与范围并同意；保留发起授权的桌面应用以接收 code 和校验 state。
3. 应用使用 PKCE 交换令牌，成功后保存访问令牌及服务返回的刷新令牌。再运行 source_test({"sourceSlug":"github-oauth"})，实际 GET user 核对身份。
4. 测试刷新需等令牌到期或按供应商允许的方式验证；没有 refresh_token 的服务不能承诺自动续期。失败先查 redirect_uri、clientSecret、scope、离线授权与服务错误。

测试端点#

测试端点用来确认这个来源真的连得上。校验时工作台会请求这个地址，一次性验证基地址可达、凭据有效、服务响应正常。

testEndpoint 支持 method（GET 或 POST）、path，以及可选 body 和 headers；查询参数写进 path。选择无副作用且确实要求同一凭据的接口。

令牌续期#

有些服务不提供标准 OAuth，却有自己的令牌刷新接口。这类接口来源可以配置续期端点：令牌即将过期时，工作台自动调用它换取新令牌，不需要人工重新认证。

续期请求默认把当前令牌放在 Authorization 请求头里；如果配置了请求体，字符串里的 {{token}} 会被替换成当前令牌，嵌套对象同样生效。

为什么用接口来源#

接口来源的价值在于覆盖面：只要对方有 HTTP 接口，就不需要对方配合改造。内部系统、自建服务和只提供文档的服务都能用同样一套方式接进来。

配置成本也很低。填好基地址、选一种认证方式、给一个测试端点，通常几分钟就能完成，剩下的请求细节交给 Agent 现场决定。

• 通用兼容：任何提供 REST 接口的服务都能接入，不要求对方发布额外组件。
• 配置简单：基地址加认证信息就是最小配置，其余参数按需补充。
• 请求灵活：方法、路径、查询参数与请求体都可以由 Agent 按接口文档决定。
• 凭据集中保管：访问凭据保存在专门的凭据存储里，不写进来源配置文件。

MCP 与接口来源对比#

两种来源解决的问题重叠，选择标准很实际：有现成 MCP 服务就用 MCP，只有 HTTP 接口就用接口来源，需要任意 HTTP 访问时也用接口来源。

两者可以并存。先用 MCP 覆盖需要细粒度工具的服务，再用接口来源补上只有 HTTP 接口的系统，按分工配置比强行统一更省事。

实用示例#

API 工具接受 {"path":"相对路径","method":"GET","params":{}}。GET 的 params 编码为查询参数；POST/PUT/PATCH 的 params 默认是 JSON 请求体。认证由来源注入。

需要表单或原始内容时，把字符串放在 params._rawBody，用 params._contentType 指定 MIME。按下面的服务配方设置认证，先调用不会发送消息的测试入口，再检查实际业务权限。

• 基地址带版本号时把版本写进基地址，例如 https://api.example.com/v1/。
• 多租户服务把租户写进基地址，例如 https://your-tenant.api.example.com/。
• 自建或内网服务同样可用，但要确认运行环境能访问该地址。
• 需要发送非 JSON 内容时用 _rawBody 传原始文本，用 _contentType 指定内容类型。
• 校验失败先查基地址与凭据，再查测试端点路径是否写对。
• 请求报错时对照接口文档确认参数、路径与请求体格式，并留意限流或额度问题。

GitHub REST#

基地址 https://api.github.com/；选择 bearer，在专用凭据框输入限定仓库和权限的 PAT，testEndpoint 为 GET user。无需把 gh 的认证复制出来；已登录 gh 时可直接使用 CLI，详见来源清单。

1. 运行 source_test({"sourceSlug":"github-api"})，核对返回账号。
2. 先 GET repos/{owner}/{repo}/issues?state=open&per_page=5，记录 owner/repo 与分页；创建 issue 使用 POST 同一路径，body 的 title 必填，须单独获准。

OpenAI API#

使用 OpenAI 项目 API Key，authType 为 bearer。先用 GET models 检查 Key 可见的模型；它不验证生成额度或某个具体模型的推理请求。

Stripe#

Stripe 支持 HTTP Basic：用户名为 Secret/Restricted API Key，密码为空。请 Agent 用 source_credential_prompt({"sourceSlug":"stripe","mode":"basic","passwordRequired":false}) 收集；示例优先使用测试模式及限制读取权限的 Key。

• GET balance 核对 livemode 和币种。创建资源等表单请求需 _rawBody 与 application/x-www-form-urlencoded；不要默认发送 JSON。

SendGrid#

SendGrid v3 使用 API Key 的 Bearer 认证。testEndpoint 选择你已授予的只读入口，例如 GET user/profile；只有 Mail Send 权限的 Key 可能没有读取 profile 权限，应按服务文档选择测试，不为通过测试扩大权限。

• 发送入口为 POST mail/send，JSON body 需要 personalizations、from、subject 和 content。先核对已验证的发件身份、收件人和正文，连接测试不发送邮件。

Twilio#

Twilio 使用 Basic。生产推荐 API Key SID / API Key Secret；本机测试也可用 Account SID / Auth Token。这两种凭据对不能混用；账号资源路径仍用 Account SID。

• 用专用用户名/密码框保存凭据，再测试账号读取。发送短信为 POST Accounts/{AccountSid}/Messages.json，params 示例为 {"_rawBody":"To=%2B15550000001&From=%2B15550000002&Body=Example","_contentType":"application/x-www-form-urlencoded"}；号码仅为格式示意，不执行发送。