Intégrations et API
Les services publics API et MCP sont facultatifs. Exposez-les lorsque vous souhaitez que des intégrations externes ou des clients IA atteignent votre déploiement.
Les deux sont des services distincts dans le fichier de composition, vous pouvez donc en ajouter un plus tard sans toucher à l'application. Voir Services et routage pour les domaines et les ports.
API publique
Le service API public est utilisé pour les intégrations, les webhooks et les documents API.
Une fois exposée, la référence de l'API est disponible à l'adresse :
| Chemin | Utiliser |
|---|---|
/docs | Référence scalaire interactive. |
/swagger | Référence de l'interface utilisateur Swagger. |
/openapi.json | Document OpenAPI pour la génération du SDK. |
/webhook-event-types | Liste actuelle des types d’événements webhook que ce déploiement peut envoyer. |
Par exemple :
https://api.kanera.example.com/docs
https://api.kanera.example.com/webhook-event-types
Voir API pour les clés API, les premières requêtes, les webhooks et la vérification des signatures.
MCP
Le service MCP permet aux clients IA de se connecter à Kanera via Streamable HTTP.
Une fois exposé, le point final est :
https://mcp.kanera.example.com/mcp
Le /health le chemin est exposé à côté. Kanera montre aux utilisateurs l'adresse MCP exacte à donner à leur client IA sous Paramètres du profil -> Clés API, alors dirigez les gens vers cet endroit plutôt que de leur demander d'assembler l'URL.
Définissez l'URL MCP publique lors de son exposition :
MCP_SERVER_PUBLIC_URL=https://mcp.kanera.example.com/mcp
Dans Docker Compose, conservez l'URL interne de l'API MCP vers public comme :
KANERA_PUBLIC_API_URL=http://public-api:3001
Les clients MCP s'authentifient avec les clés API Kanera en utilisant :
Authorization: Bearer kanera_live_...
Utilisez une clé personnelle de Paramètres du profil -> Clés API pour le propre client IA d'un utilisateur sur ses tableaux accessibles. Utiliser une clé d'espace de travail de Paramètres de l'espace de travail -> API pour les clients MCP partagés ou les automatisations côté serveur épinglées sur un seul espace de travail.
OAuth pour les agents IA
Pour permettre aux agents compatibles de se connecter via une connexion au navigateur au lieu d'une clé API, indiquez à Kanera ses URL OAuth publiques. Définissez l'émetteur d'API publique sur le public-api prestation :
PUBLIC_API_OAUTH_ISSUER=https://api.kanera.example.com
Générez un secret distinct pour l'échange de jetons MCP privé vers API publique :
MCP_INTERNAL_SECRET=<output of openssl rand -hex 32>
La valeur doit comporter au moins 32 caractères et doit différer de JWT_SECRET, et doit être identique dans le public-api et mcp prestations. Le fichier Compose fourni le transmet aux deux services.
MCP_SERVER_PUBLIC_URL (défini ci-dessus) gère les métadonnées des ressources protégées MCP. Avec le pack docker-compose.yml, deux autres variables sont dérivées automatiquement : MCP_PUBLIC_URL (la ressource canonique OAuth et l'adresse MCP affichées aux utilisateurs) à partir de MCP_SERVER_PUBLIC_URL, et le service MCP OAUTH_ISSUER_URL de PUBLIC_API_OAUTH_ISSUER.
Les demandes d'autorisation et de jeton OAuth lient chaque code, octroi, famille d'actualisation et jeton d'accès à ce canonique. MCP_PUBLIC_URL. Brut kanera_mcp_... les jetons fonctionnent uniquement au point de terminaison MCP et sont rejetés par /api/v1; le service MCP les échange en interne contre un identifiant de délégation distinct d'une durée d'une minute.
Acheminez les chemins de découverte OAuth vers le bon service sur votre proxy inverse :
| Chemin | Service |
|---|---|
/.well-known/oauth-authorization-server, /oauth/* | public-api |
/.well-known/oauth-protected-resource, /.well-known/oauth-protected-resource/mcp, /mcp | mcp |
Lors de la mise à niveau à partir d'une version qui émettait des jetons OAuth sans liaison de ressources, la migration révoque les autorisations et jetons OAuth existants. Les définitions de clients enregistrées restent, mais les utilisateurs et les agents sans surveillance doivent se reconnecter une fois après cette ancienne migration. La mise à jour de la stratégie de lecture/écriture ne révoque pas les sessions OAuth valides et ne nécessite donc pas de reconnexion.
Voir Connecter un agent IA pour le flux complet, et Connectez Kanera à votre agent IA pour la configuration du client et les fonctionnalités MCP.
Copie des pièces jointes d'importation Trello
Les importations JSON de la carte Trello fonctionnent sans configuration supplémentaire.
Pour permettre aux utilisateurs d'importer des pièces jointes Trello dans Kanera, configurez une clé API Trello :
TRELLO_API_KEY=your-trello-api-key
Créez la clé à partir de la page d'administration Power-Up de Trello à l'adresse https://trello.com/power-ups/admin. Aucune capacité de mise sous tension n'est requise ; l'entrée Power-Up/app est uniquement le conteneur Trello pour la clé API. Les utilisateurs connectent Trello pendant l'importation afin que Kanera puisse copier les pièces jointes pour cette importation.
Voir Importer depuis Trello.