API

概览

使用灵活的 HTTP 工具连接任何 REST API

只需告诉您的 Agent。 连接 API 最简单的方式是告诉您的 Agent 您的需求：

“连接 JSONPlaceholder API”
“为我公司的内部 API 添加访问权限”
“使用我的 API 密钥设置天气 API”

Agent 会自动处理配置、凭据和验证。

API 来源提供了一个灵活的 HTTP 工具，让您的 Agent 连接几乎任何 REST API。如果某个服务提供 API，您的 Agent 就能使用它 —— 无需 MCP 服务器。

工作原理#

当您配置 API 来源时，xiantong 会：

创建一个用于发送请求的灵活 HTTP 工具
处理认证，通过安全存储和注入凭据
验证连接，使用测试端点
允许 Agent 对 API 的基础 URL 发起任意请求

最终结果：您的 Agent 能够调用已配置 API 上的任何端点。

配置#

API 来源通过 JSON 文件配置：

{
"type": "api",
"name": "My API",
"tagline": "Description of the API",
"icon": "https://example.com/icon.png",
"api": {
"baseUrl": "https://api.example.com/",
"testEndpoint": {
"method": "GET",
"path": "health"
},
"authType": "bearer"
}
}

配置字段#

字段	是否必填	描述
`type`	是	必须为 `"api"`
`name`	是	来源的显示名称
`tagline`	否	简短描述
`icon`	否	图标 URL、表情或本地文件（自动发现：`icon.svg`、`icon.png`）
`api.baseUrl`	是	所有 API 请求的基础 URL
`api.testEndpoint`	否	用于验证连接的对象：`{ method: "GET" \| "POST", path: "endpoint", body?: {}, headers?: {} }`
`api.authType`	是	认证方式（见下文）
`api.headerName`	否	`header` 认证类型的自定义头部名称
`api.queryParam`	否	`query` 认证类型的查询参数名称
`api.authScheme`	否	`bearer` 认证的前缀（默认 `"Bearer"`，也可为 `"Token"`）
`api.headerNames`	否	多头认证使用的头部名称数组（例如 `[`DD-API-KEY`,` DD-APPLICATION-KEY`]`）
`api.oauth`	否	通用 OAuth 2.0 配置块（详见下文 OAuth 2.0 部分）

身份验证类型#

API 来源支持六种认证方式：

Bearer 令牌#

{
"api": {
"baseUrl": "https://api.example.com",
"authType": "bearer"
}
}

发送 Authorization: Bearer {token}。

头部认证#

{
"api": {
"baseUrl": "https://api.example.com",
"authType": "header",
"headerName": "X-API-Key"
}
}

通过自定义头部发送凭据：X-API-Key: {token}。

查询参数认证#

{
"api": {
"baseUrl": "https://api.example.com",
"authType": "query",
"queryParam": "api_key"
}
}

将凭据作为查询参数附加：?api_key={token}。

OAuth 2.0#

分为 自动发现（推荐）和 显式配置（适用于不支持标准元数据的提供方）。

自动发现（推荐）

如果 API 支持 RFC 9728（OAuth 受保护资源元数据），只需设置 authType —— xiantong 会自动处理端点和客户端注册：

{
"api": {
"baseUrl": "https://api.example.com/v1/",
"authType": "oauth"
}
}

xiantong 会请求基础 URL，读取 WWW-Authenticate 头部，发现 OAuth 元数据，动态注册客户端并启动授权流程。无需 oauth 配置块。

显式配置

对于不公开标准 OAuth 元数据的服务（如 GitHub、Linear），请手动提供端点：

{
"api": {
"baseUrl": "https://api.github.com/",
"authType": "oauth",
"oauth": {
"authorizationUrl": "https://github.com/login/oauth/authorize",
"tokenUrl": "https://github.com/login/oauth/access_token",
"clientId": "your_client_id",
"clientSecret": "your_client_secret",
"scopes": ["repo", "read:user"]
}
}

字段	是否必填	描述
`oauth.authorizationUrl`	是	OAuth 授权端点
`oauth.tokenUrl`	是	OAuth 令牌交换端点
`oauth.clientId`	是	您的 OAuth 应用客户端 ID
`oauth.clientSecret`	否	客户端密钥（公共 PKCE 客户端可不填）
`oauth.scopes`	否	请求的 OAuth 范围
`oauth.audience`	否	类似 Auth0 的 audience 参数
`oauth.extraParams`	否	额外的授权 URL 参数

两种模式均支持完整的 PKCE OAuth 2.0 流程。令牌会自动刷新，并以 Authorization: Bearer {token} 发送。

对于 Google、Microsoft 和 Slack API，xiantong 提供内置的 OAuth 支持，并预配置了作用域 —— 无需手动配置 oauth 块。只需设置相应的 provider 字段。

无需认证#

{
"api": {
"baseUrl": "https://api.example.com",
"authType": "none"
}
}

适用于无需认证的公共 API。

Basic 认证#

{
"api": {
"baseUrl": "https://api.example.com",
"authType": "basic"
}
}

发送 Authorization: Basic {base64(username:password)}。

多头认证#

{
"api": {
"baseUrl": "https://api.example.com",
"authType": "header",
"headerNames": ["X-API-KEY", "X-APP-KEY"]
}
}

将多个凭据分别作为头部发送。数组中的每个头部名称在认证时都会生成一个输入字段。所有头部都会包含在每次 API 请求中。

当 API 要求同时提供两个或多个认证头部时使用多头认证。这种情况常见于将身份与授权分开的服务，或要求同时提供 API 密钥与应用密钥的接口。

常见用例：

Datadog：DD-API-KEY + DD-APPLICATION-KEY
需要身份与签名密钥的 API：单独的 API 密钥和密钥
应用 + 用户凭据服务：应用密钥加用户令牌

测试端点#

testEndpoint 字段指定用于验证连接的端点。测试来源时，xiantong 会请求此端点以确认：

基础 URL 可访问
认证凭据有效
API 响应正常

常见测试端点：

API 类型	测试端点
健康检查	`/health`
用户信息	`/me`、`/user`
API 状态	`/status`、`/ping`

选择一个轻量级且需要认证的端点，以便一次请求验证连接性与凭据。

为什么使用 API 来源？#

通用兼容性

任何提供 REST API 的服务都可以集成。

简单配置

只需提供基础 URL 和认证信息。

灵活请求

HTTP 工具可发送任意 API 请求。

安全凭据

API 密钥加密存储，不写入配置文件。

比较：MCP vs API 来源#

功能	MCP 来源	API 来源
设置	需要 MCP 服务器 URL	只需基础 URL + 认证配置
工具	由服务器预定义	灵活的 HTTP 工具
认证	OAuth 或 bearer	OAuth、bearer、header、query、basic、none
适用场景	支持 MCP 的服务	任何 REST API

如果可用，请使用 MCP 来源以获取预定义工具的更丰富整合。若服务无 MCP 支持或需要灵活 HTTP 访问，请使用 API 来源。

需要 Google、Microsoft 或 Slack？ xiantong 对这些服务提供内置 OAuth 支持并预定义作用域 —— 只需告诉您的 Agent“连接 Google 日历”或“添加 Slack”，它就会引导您完成 OAuth 流程。需要其他 OAuth 提供方？ 使用 authType: "oauth" 及 oauth 配置块连接 GitHub、Linear、Notion、Spotify 或任何其他 OAuth 2.0 服务。

下一步#

实战示例#

API 来源配置的真实示例。

概览