Integraciones y API
Los servicios públicos API y MCP son opcionales. Expóngalos cuando desee que integraciones externas o clientes de IA lleguen a su implementación.
Ambos son servicios separados en el archivo de redacción, por lo que puedes agregar cualquiera de ellos más tarde sin tocar la aplicación. Ver Servicios y enrutamiento para dominios y puertos.
API pública
El servicio API público se utiliza para integraciones, webhooks y documentos API.
Cuando se expone, la referencia de API está disponible en:
| Camino | uso |
|---|---|
/docs | Referencia escalar interactiva. |
/swagger | Referencia de la interfaz de usuario de Swagger. |
/openapi.json | Documento OpenAPI para generación de SDK. |
/webhook-event-types | Lista actual de tipos de eventos de webhook que esta implementación puede enviar. |
Por ejemplo:
https://api.kanera.example.com/docs
https://api.kanera.example.com/webhook-event-types
Ver API para claves API, primeras solicitudes, webhooks y verificación de firmas.
MCP
El servicio MCP permite a los clientes de IA conectarse a Kanera a través de HTTP Streamable.
Cuando se expone, el criterio de valoración es:
https://mcp.kanera.example.com/mcp
el /health El camino está expuesto a su lado. Kanera muestra a los usuarios la dirección MCP exacta para darle a su cliente de IA en Configuración de perfil -> Claves API, así que indique a las personas allí en lugar de pedirles que reúnan la URL.
Configure la URL pública de MCP al exponerla:
MCP_SERVER_PUBLIC_URL=https://mcp.kanera.example.com/mcp
En Docker Compose, mantenga la URL interna de MCP a API pública como:
KANERA_PUBLIC_API_URL=http://public-api:3001
Los clientes MCP se autentican con claves API de Kanera usando:
Authorization: Bearer kanera_live_...
Utilice una clave personal de Configuración de perfil -> Claves API para el propio cliente de IA de un usuario en sus tableros accesibles. Utilice una clave de espacio de trabajo de Configuración del espacio de trabajo -> API para clientes MCP compartidos o automatizaciones del lado del servidor ancladas a un espacio de trabajo.
OAuth para agentes de IA
Para permitir que los agentes compatibles se conecten a través de un inicio de sesión en el navegador en lugar de una clave API, informe a Kanera sus URL públicas de OAuth. Configure el emisor de API pública en el public-api servicio:
PUBLIC_API_OAUTH_ISSUER=https://api.kanera.example.com
Genere un secreto separado para el intercambio de tokens privado de MCP a API pública:
MCP_INTERNAL_SECRET=<output of openssl rand -hex 32>
El valor debe tener al menos 32 caracteres y debe diferir de JWT_SECRET, y debe ser idéntico en el public-api y mcp servicios. El archivo Compose incluido lo pasa a ambos servicios.
MCP_SERVER_PUBLIC_URL (establecido arriba) controla los metadatos de recursos protegidos de MCP. con el paquete docker-compose.yml, dos variables más se derivan automáticamente: MCP_PUBLIC_URL (el recurso canónico de OAuth y la dirección MCP que se muestran a los usuarios) de MCP_SERVER_PUBLIC_URLy el servicio MCP OAUTH_ISSUER_URL de PUBLIC_API_OAUTH_ISSUER.
Las solicitudes de autorización y token de OAuth vinculan cada código, concesión, actualización de familia y token de acceso a ese código canónico. MCP_PUBLIC_URL. crudo kanera_mcp_... Los tokens funcionan solo en el punto final de MCP y son rechazados por /api/v1; el servicio MCP los intercambia internamente por una credencial de delegación separada de un minuto de duración.
Enrute las rutas de descubrimiento de OAuth al servicio correcto en su proxy inverso:
| Camino | Servicio |
|---|---|
/.well-known/oauth-authorization-server, /oauth/* | public-api |
/.well-known/oauth-protected-resource, /.well-known/oauth-protected-resource/mcp, /mcp | mcp |
Al actualizar desde una versión que emitió tokens de OAuth sin vinculación de recursos, la migración revoca las concesiones y tokens de OAuth existentes. Las definiciones de clientes registrados permanecen, pero los usuarios y los agentes desatendidos deben volver a conectarse una vez después de esa migración anterior. La actualización de la política de lectura/escritura no revoca sesiones OAuth válidas, por lo que no requiere reconexión.
Ver Conecte un agente de IA para el flujo completo, y Conecte Kanera con su agente de IA para la configuración del cliente y las capacidades de MCP.
Copiar archivos adjuntos de importación de Trello
Las importaciones JSON del tablero Trello funcionan sin configuración adicional.
Para permitir a los usuarios importar archivos adjuntos de Trello a Kanera, configure una clave API de Trello:
TRELLO_API_KEY=your-trello-api-key
Cree la clave desde la página de administración de encendido de Trello en https://trello.com/power-ups/admin. No se requieren capacidades de encendido; la entrada Power-Up/app es solo el contenedor Trello para la clave API. Los usuarios conectan Trello durante la importación para que Kanera pueda copiar los archivos adjuntos para esa importación.