用途:任何对外部 API 的读写请求都应通过 Nango 处理,不使用 MCP、厂商 CLI 或临时直连方式。
配置(必需):按顺序解析密钥,先读进程环境变量 NANGO_TOOLBOX_SECRET_KEY,再读本地 .env;缺失时提示用户注册 Nango 账号(https://app.nango.dev/signup),从 Environment settings → Backend 复制密钥并写入 shell 配置。若其他指令提到 NANGO_SECRET_KEY,视为 NANGO_TOOLBOX_SECRET_KEY。基础地址依次取 NANGO_SERVER_URL 环境变量、本地 .env,默认 https://api.nango.dev。请求头:Authorization: Bearer <NANGO_TOOLBOX_SECRET_KEY>,Content-Type: application/json;同时存在 JSON body 与查询参数时优先 JSON body。
发现:先查询集成 GET <base-url>/integrations,再按 integrationId 查询连接 GET <base-url>/connections?integrationId=<unique_key>,以及已部署动作/同步 GET <base-url>/scripts/config,均应带 Authorization 头。
选择集成与连接:确认目标 API 的集成是否已存在,不存在则为用户创建。OAuth 且已有 Nango 开发者凭据时,请用户在仪表盘手动启用;无开发者凭据时引导获取 client id 与 secret;使用 OAuth client credentials 时不要让用户提供 client id 与 secret,由用户通过 Connect Link 填写。不要索取连接级参数,交由 Connect Link 处理。若存在多个连接且无法区分,询问使用哪个 connection_id。
无连接时生成连接会话链接:POST <base-url>/connect/sessions,JSON 体含 tags 与 allowed_integrations,把返回的 data.connect_link 直接给用户(约 30 分钟过期),不要引导去仪表盘。调用前确认连接所需 scope(常见于 credentials.raw.scope);不足时先更新集成级 scope,再征得用户同意删除并重建连接。scope 用逗号分隔、不加空格。
访问策略:1–2 次简单调用或探索 API 时用 Nango proxy;多调用逻辑、转换、分页编排、重试与错误处理或需要复用时用 Nango Action,优先复用已部署动作。新建动作需使用 building-nango-functions-remotely 技能并部署后再调用;该技能不存在时可提供从 https://github.com/NangoHQ/skills 安装。调用已部署动作:POST <base-url>/action/trigger,带 Provider-Config-Key、Connection-Id 头及 action_name 与 input。
文档:https://nango.dev/docs、https://nango.dev/docs/llms.txt、https://nango.dev/docs/reference/api、https://nango.dev/docs/spec.yaml。
限制:具体计费、价格与可用平台暂未提供;实际支持的集成与 scope 需以 Nango 文档和接口返回为准。