整合與 API
公共 API 和 MCP 服務是可選的,當您希望外部整合或 AI 客戶端訪問您的部署時,可以公開它們。
兩者在撰寫檔案中都是單獨的服務，因此您可以稍後新增其中之一，而無需觸控應用程式。參見 服務與路由 域和埠。
公共API
公共 API 服務用於整合、webhook 和 API 文件。
當公開時,API 參考可在以下位置獲得:
| 路徑 | 使用 |
|---|---|
/docs | 互動式標量參考。 |
/swagger | Swagger UI 參考。 |
/openapi.json | 用於 SDK 生成的 OpenAPI 文件。 |
/webhook-event-types | 當前列表中此部署可以傳送的 webhook 事件型別。 |
例如：
https://api.kanera.example.com/docs
https://api.kanera.example.com/webhook-event-types
海 API 用於 API 金鑰、首次請求、webhook 和簽名驗證。
MCP
MCP 服務允許 AI 客戶端透過 Streamable HTTP 連線到 Kanera。
暴露時，終點為：
https://mcp.kanera.example.com/mcp
該 /health Kanera 向使用者顯示確切的 MCP 地址,以便在其 AI 客戶端的控制下, 配置檔案設定 -> API 金鑰，所以將人們指向那裡，而不是要求他們組裝 URL。
設定公開 MCP URL 時:
MCP_SERVER_PUBLIC_URL=https://mcp.kanera.example.com/mcp
在 Docker Compose 中,將內部 MCP-to-public-API URL 保持為:
KANERA_PUBLIC_API_URL=http://public-api:3001
MCP 客戶端使用 Kanera API 金鑰進行身份驗證,方法如下:
Authorization: Bearer kanera_live_...
使用來自 配置檔案設定 -> API 金鑰 使用者自己的 AI 客戶端在其無障礙板中使用工作區鍵 工作區設定 -> API 用於共享 MCP 客戶端或固定到一個工作區的伺服器端自動化。
面向 AI 代理的 OAuth
若要讓相容的代理透過瀏覽器登入而不是 API 金鑰連線，請為 Kanera 配置其公共 OAuth URL。將公共 API 的頒發者設定在 public-api 服務：
PUBLIC_API_OAUTH_ISSUER=https://api.kanera.example.com
為私有 MCP 到公共 API 令牌交換生成單獨的秘密:
MCP_INTERNAL_SECRET=<output of openssl rand -hex 32>
值必須至少為32個字元,必須不同於 JWT_SECRET，並且必須相同 public-api 以及 mcp 捆綁的 Compose 檔案將其傳遞給這兩個服務。
MCP_SERVER_PUBLIC_URL （上面設定）驅動 MCP 受保護資源後設資料。與捆綁的 docker-compose.yml，另外兩個變數會自動匯出： MCP_PUBLIC_URL （向使用者顯示的規範 OAuth 資源和 MCP 地址）來自 MCP_SERVER_PUBLIC_URL，以及 MCP 服務的 OAUTH_ISSUER_URL 從 PUBLIC_API_OAUTH_ISSUER.
OAuth 授權和令牌請求將每個程式碼、授權、重新整理系列和訪問令牌繫結到該規範 MCP_PUBLIC_URL。原料 kanera_mcp_... 只能在 MCP 端點上工作,並且被拒絕 /api/v1; MCP 服務在內部將它們交換為單獨的短暫授權憑證。
將 OAuth 發現路徑路由到您的反向代理上的正確服務:
| 路徑 | 服務 |
|---|---|
/.well-known/oauth-authorization-server, /oauth/* | public-api |
/.well-known/oauth-protected-resource, /.well-known/oauth-protected-resource/mcp, /mcp | mcp |
從釋出了 OAuth 令牌但未繫結資源的版本升級時,遷移會撤銷現有的 OAuth 授權和令牌。 已註冊的客戶端定義保留,但使用者和無人值守代理必須在該舊版遷移後重新連線一次。 讀/寫策略更新不會撤銷有效的 OAuth 會話,因此不需要重新連線。
海 連線 AI 代理 對於全流,以及 將 Kanera 連線到您的 AI 代理 用於客戶端設定和 MCP 功能。
Trello 匯入附件複製
Trello 板 JSON 匯入工作,無需額外設定。
要讓使用者將 Trello 檔案附件匯入到 Kanera,請配置 Trello API 金鑰:
TRELLO_API_KEY=your-trello-api-key
從 Trello 的 Power-Up 管理頁面建立金鑰 https://trello.com/power-ups/admin。無需 Power-Up 功能； Power-Up/app 條目只是 API 金鑰的 Trello 容器。使用者在匯入期間連線 Trello，以便 Kanera 可以複製該匯入的附件。
海 從 Trello 匯入.