Integrações e APIs
Os serviços públicos de API e MCP são opcionais. Exponha-os quando desejar que integrações externas ou clientes de IA cheguem à sua implantação.
Ambos são serviços separados no arquivo de composição, então você pode adicionar qualquer um deles posteriormente sem tocar no aplicativo. Veja Serviços e roteamento para domínios e portas.
API pública
O serviço de API público é usado para integrações, webhooks e documentos de API.
Quando exposta, a referência da API está disponível em:
| Caminho | Usar |
|---|---|
/docs | Referência escalar interativa. |
/swagger | Referência da IU do Swagger. |
/openapi.json | Documento OpenAPI para geração de SDK. |
/webhook-event-types | Lista atual de tipos de eventos de webhook que esta implantação pode enviar. |
Por exemplo:
https://api.kanera.example.com/docs
https://api.kanera.example.com/webhook-event-types
Veja API para chaves de API, primeiras solicitações, webhooks e verificação de assinatura.
MCP
O serviço MCP permite que clientes de IA se conectem ao Kanera por meio de Streamable HTTP.
Quando exposto, o endpoint é:
https://mcp.kanera.example.com/mcp
O /health caminho é exposto ao lado dele. Kanera mostra aos usuários o endereço MCP exato para fornecer ao cliente de IA Configurações de perfil -> Chaves de API, então direcione as pessoas para lá em vez de pedir que montem o URL.
Defina o URL público do MCP ao expô-lo:
MCP_SERVER_PUBLIC_URL=https://mcp.kanera.example.com/mcp
No Docker Compose, mantenha o URL interno do MCP para a API pública como:
KANERA_PUBLIC_API_URL=http://public-api:3001
Os clientes MCP são autenticados com chaves de API Kanera usando:
Authorization: Bearer kanera_live_...
Use uma chave pessoal de Configurações de perfil -> Chaves de API para o cliente de IA do próprio usuário em seus painéis acessíveis. Use uma chave de espaço de trabalho de Configurações do espaço de trabalho -> API para clientes MCP compartilhados ou automações do lado do servidor fixadas em um espaço de trabalho.
OAuth para agentes de IA
Para permitir que agentes compatíveis se conectem por meio de login no navegador em vez de uma chave de API, informe ao Kanera seus URLs OAuth públicos. Defina o emissor da API pública no public-api serviço:
PUBLIC_API_OAUTH_ISSUER=https://api.kanera.example.com
Gere um segredo separado para a troca de tokens privados de MCP para API pública:
MCP_INTERNAL_SECRET=<output of openssl rand -hex 32>
O valor deve ter pelo menos 32 caracteres, deve ser diferente de JWT_SECRET, e devem ser idênticos no public-api e mcp serviços. O arquivo Compose incluído o transmite para ambos os serviços.
MCP_SERVER_PUBLIC_URL (definido acima) orienta os metadados de recursos protegidos do MCP. Com o pacote docker-compose.yml, mais duas variáveis são derivadas automaticamente: MCP_PUBLIC_URL (o recurso OAuth canônico e o endereço MCP mostrado aos usuários) de MCP_SERVER_PUBLIC_URLe o serviço MCP OAUTH_ISSUER_URL de PUBLIC_API_OAUTH_ISSUER.
Solicitações de autorização e token OAuth vinculam cada código, concessão, família de atualização e token de acesso a esse código canônico MCP_PUBLIC_URL. Cru kanera_mcp_... os tokens funcionam apenas no endpoint MCP e são rejeitados por /api/v1; o serviço MCP os troca internamente por uma credencial de delegação separada com duração de um minuto.
Roteie os caminhos de descoberta do OAuth para o serviço correto em seu proxy reverso:
| Caminho | Serviço |
|---|---|
/.well-known/oauth-authorization-server, /oauth/* | public-api |
/.well-known/oauth-protected-resource, /.well-known/oauth-protected-resource/mcp, /mcp | mcp |
Ao atualizar de uma versão que emitiu tokens OAuth sem vinculação de recursos, a migração revoga concessões e tokens OAuth existentes. As definições de clientes registrados permanecem, mas os usuários e agentes autônomos devem se reconectar uma vez após a migração mais antiga. A atualização da política de leitura/gravação não revoga sessões OAuth válidas, portanto, não requer reconexão.
Veja Conecte um agente de IA para o fluxo total e Conecte Kanera ao seu agente de IA para configuração do cliente e recursos de MCP.
Cópia de anexo de importação do Trello
As importações JSON do quadro Trello funcionam sem configuração extra.
Para permitir que os usuários importem anexos de arquivo do Trello para o Kanera, configure uma chave de API do Trello:
TRELLO_API_KEY=your-trello-api-key
Crie a chave na página de administração do Power-Up do Trello em https://trello.com/power-ups/admin. Não são necessários recursos de inicialização; a entrada Power-Up/app é apenas o contêiner Trello para a chave API. Os usuários conectam o Trello durante a importação para que o Kanera possa copiar os anexos dessa importação.
Veja Importar do Trello.