连接器 API

Claude / ChatGPT App / MCP

Claude 和 ChatGPT 可以通过远程 MCP 端点连接 Vernclaw：

• POST /mcp

MCP Server 暴露平台级工具，并把每个 active Vernclaw connector 暴露成独立 MCP tool。例如 seo.website-traffic 会暴露为 vernclaw_seo_dot_website_dash_traffic，并带上对应 connector 的 input schema。

• vernclaw_list_connectors
• vernclaw_get_connector_job
• 由 active connector ID 生成的 connector tools

Tool descriptor 会包含 OpenAI 评审需要的 annotations。read_only connectors 标记为 readOnlyHint: true；generation connectors 和异步任务轮询会创建任务、扣积分或持久化结果，因此标记为非只读。Vernclaw connector tools 默认标记为非 destructive、open-world，因为它们会调用托管外部 provider 或公开网页平台。

安装时使用带 PKCE 的 OAuth 2.1。Vernclaw 提供所需的发现与授权端点：

• GET /.well-known/oauth-protected-resource
• GET /.well-known/oauth-authorization-server
• POST /oauth/register
• GET /oauth/authorize
• POST /oauth/token

OAuth 流程会把 Claude 或 ChatGPT 用户绑定到现有 Vernclaw 账号，并签发由现有 API Key runtime 支撑的 bearer token。连接器调用仍然走原本的安装状态、积分、缓存、provider 和审计检查。 Token endpoint 同时支持 authorization_code 和 refresh_token grants，因此客户端可以保持已有安装授权，不需要反复要求用户重新连接。 未认证的 MCP 请求会在工具发现前收到带有 WWW-Authenticate challenge 的 401 Unauthorized，其中指向 protected-resource metadata。

Claude custom connector 可以使用动态 client registration，也可以使用用户自己的 OAuth client。当 Claude Advanced settings 要求填写 OAuth 凭据时，在 API 密钥 中生成：

• Server URL：https://vernclaw.com/mcp
• OAuth Client ID：生成的 client ID
• OAuth Client Secret：生成的 client secret

每组 OAuth client 都归属于一个 Vernclaw 用户。授权时，当前登录的 Vernclaw 账号必须匹配该 client ID 的 owner。OAuth client secret 不会被当作普通 API key 接受。

鉴权

连接器 API 复用站点现有的 API Key 体系。

• Authorization: Bearer <api_key>
• x-api-key: <api_key>

端点

• GET /api/connectors
• GET /api/connectors?format=markdown
• GET /api/connectors/[connectorId]
• GET /api/connectors/[connectorId]?format=markdown
• POST /api/connectors/[connectorId]/invoke
• GET /api/connectors/jobs/[jobId]
• GET /api/connectors/status
• GET /api/connectors/balance（兼容别名）

输出契约

连接器调用、任务轮询、账号状态和余额接口返回 JSON，content-type 为 application/json。成功调用和任务响应直接返回面向 CLI 和 agent 的紧凑标准化字段。完整上游 provider payload 会保留在服务端 task、audit 和 cache 记录中，用于排障。

目录和详情接口默认返回 JSON。format=markdown 变体仅作为浏览器/文档兼容视图；CLI 消费 JSON，并且只在本地按 --pretty 渲染终端可读输出。

CLI 会在输出到 stdout 前把 HTTP payload 包装为 { "status": <http_status>, "data": <payload> }。业务错误在 invoke 和 job 响应中同样返回紧凑 JSON，并通过 x-error-code 提供机器可读错误码。