Note
Le MCP Server pour le Fin Agent API est actuellement en version bêta et peut changer considérablement avant la version finale. Vos retours sont les bienvenus et aideront à orienter l'avenir de cette fonctionnalité produit.
Le Fin Agent API expose un serveur distant Model Context Protocol (MCP) qui permet aux agents IA externes d'appeler Fin comme un outil. Au lieu de reconstruire la logique de support dans votre propre agent, vous pouvez connecter directement la knowledge base, les procédures et les capacités de conversation multi-tours de Fin depuis n'importe quel client compatible MCP — y compris Claude, Claude Code, Cursor ou votre propre framework d'agent.
Il existe deux façons de se connecter, selon le rôle du client :
| Coéquipier | Utilisateur final |
URL | ||
Authentifie | Un espace de travail, via la clé api Fin Agent API | Un seul utilisateur final vérifié, via un JWT Messenger |
Modèle de confiance | Backend serveur-à-serveur de confiance | Client par utilisateur non fiable (un assistant IA fonctionnant dans ou près de l'environnement de l'utilisateur final) |
Quelle identité ? | Le client affirme pour quel utilisateur final (user_id) chaque appel agit | Le jeton est l'identité — le client ne peut pas agir au nom d'une autre personne |
Détient un secret au niveau de l'application ? | Oui (la clé Fin Agent API) | Non — seulement un JWT limité à un utilisateur |
Cas d'utilisation
Le Fin Agent API MCP server est conçu pour des scénarios multi-agents où votre propre agent a besoin d'accéder aux capacités de Fin :
Support intégré dans les agents produits. Donnez à l'assistant IA de votre produit la capacité de répondre aux questions de support en utilisant votre knowledge base Fin configurée, sans dupliquer votre knowledge base ou contenu.
Automatisation des procédures. Permettez à un agent orchestrateur de déclencher des procédures Fin (remboursements, mises à niveau, annulations) au nom des users et de gérer les interactions multi-tours de manière programmatique.
Routage basé sur les capacités. Utilisez list_fin_capabilities pour déterminer quelles actions sont disponibles pour un user donné, puis orientez vers le bon outil dans la logique décisionnelle de votre agent.
Outils pour développeurs. Intégrez votre knowledge base Fin dans des outils pour développeurs comme Claude Code ou Cursor, afin que les users internes puissent interroger votre contenu de support depuis leur flux de travail existant.
Prérequis
Votre espace de travail Intercom doit avoir la fonctionnalité Fin Agent API activée. Contactez votre équipe de compte Intercom si vous n'y avez pas accès.
Points de terminaison
Il existe deux points de terminaison, selon qui fait la requête.
Point de terminaison Coéquipier
https://api.intercom.io/fin/mcp
Utilisez ceci lorsqu'un service backend de confiance appelle Fin au nom d'un user. L'appelant s'authentifie avec un jeton d'accès OAuth pour l'espace de travail. L'identité de l'utilisateur final est fournie dans le corps de la requête par le service appelant.
Ce modèle convient aux intégrations serveur-à-serveur où votre backend contrôle qui fait la requête.
Point de terminaison Utilisateur final
https://api.intercom.io/fin/mcp/{YOUR_APP_ID_CODE}Utilisez ceci lorsque le client MCP fonctionne dans ou près de l'environnement de l'utilisateur final — par exemple, un assistant IA fonctionnant localement sur la machine d'un user. L'appelant s'authentifie avec un JWT signé représentant un seul utilisateur final vérifié.
Le paramètre de chemin {YOUR_APP_ID_CODE} est l'identifiant de votre espace de travail Intercom (le même app_id utilisé dans les extraits d'installation Messenger).
L'authentification utilise le même mécanisme JWT Messenger déjà utilisé pour la vérification d'identité — si vous avez déjà configuré la vérification d'identité Messenger, aucune configuration supplémentaire n'est nécessaire côté Intercom.
Authentification
Point de terminaison Coéquipier
Passez votre clé api Fin Agent API comme jeton Bearer dans l'en-tête Authorization :
Authorization: Bearer YOUR_FIN_AGENT_API_KEY
Point de terminaison Utilisateur final
Générez un JWT signé en utilisant le secret Messenger de votre espace de travail (trouvé dans Paramètres → Sécurité → Vérification d'identité). Le JWT doit être signé avec HS256 et inclure l'ID externe de l'utilisateur dans la revendication sub. C'est exactement le même JWT que vous générez pour authentifier les utilisateurs finaux pour Messenger.
Exemple de charge utile JWT :
{
"user_id":"user@example.com"
}
Passez-le comme jeton Bearer :
Authorization: Bearer YOUR_USER_JWT
L'utilisateur identifié dans le JWT est celui auquel Fin répondra. Il utilisera cet user pour créer des conversations et faire correspondre les procédures. Votre backend génère ce jeton côté serveur et le fournit au client — ne divulguez jamais votre secret Messenger côté client.
Connexion depuis Claude
Claude Desktop
Ajoutez ce qui suit à votre claude_desktop_config.json :
Point de terminaison Coéquipier :
{
"mcpServers": {
"fin": {
"command": "npx",
"args": [
"-y",
"mcp-remote",
"https://api.intercom.io/fin/mcp",
"--header",
"Authorization: Bearer {YOUR_FIN_AGENT_API_KEY}"
}
}
}
}
Point de terminaison Utilisateur final :
{
"mcpServers": {
"fin": {
"command": "npx",
"args": [
"-y",
"mcp-remote",
"https://api.intercom.io/fin/mcp/{YOUR_APP_ID_CODE}",
"--header",
"Authorization: Bearer {YOUR_USER_JWT}"
}
}
}
}
Claude Code (CLI)
Point de terminaison Coéquipier :
claude mcp add intercom-fin \
--transport http \
https://api.intercom.io/fin/mcp \
--header "Authorization: Bearer YOUR_FIN_AGENT_API_KEY"
Point de terminaison Utilisateur final :
claude mcp add intercom-fin \
--transport http \
https://api.intercom.io/fin/mcp/YOUR_APP_ID_CODE \
--header "Authorization: Bearer YOUR_USER_JWT"
Ou ajoutez l'équivalent JSON à .mcp.json sous mcpServers.
Outils
Une fois connecté, le serveur MCP expose cinq outils au client.
list_fin_capabilities
Retourne les capacités Fin Agent API disponibles pour un user donné : les procédures adaptées à l'audience que l'user peut déclencher, plus les actions statiques disponibles pour tous les users (poser une question, répondre à une conversation).
Appelez ceci en premier pour découvrir ce que Fin peut faire pour un user spécifique avant d'appeler d'autres outils. L'accès aux procédures est adapté à l'audience — tous les users n'ont pas accès à toutes les procédures.
Entrée : user_id — l'ID externe de l'user.
Retour : Un document JSON listant les capacités disponibles, chacune avec son type, ID et nom.
ask_fin
Envoie une question ponctuelle à Fin et retourne une réponse. Fin recherche dans vos sources de connaissance configurées et renvoie une réponse directe sans démarrer une conversation persistante.
Utilisez ceci pour des recherches d'information où vous souhaitez une réponse directe et n'avez pas besoin d'un flux multi-tours.
Entrées : user_id, message (la question à poser).
get_fin_response
Interroge la réponse de Fin à une conversation ou un flux de procédure en cours. Utilisez ceci après avoir démarré une conversation ou une procédure pour récupérer la dernière réponse de Fin.
Entrée : conversation_id.
reply_to_fin_conversation
Envoie un message de suivi dans une conversation Fin existante. Utilisez ceci pour continuer une interaction multi-tours — par exemple, fournir des informations supplémentaires que Fin a demandées pendant une procédure.
Entrées : conversation_id, message.
run_fin_procedure
Déclenche une procédure Fin spécifique pour un user. Une procédure est un flux de travail multi-étapes configuré — par exemple, traiter un remboursement ou mettre à jour un abonnement. Fin démarrera la procédure, pourra demander des informations supplémentaires et conduira l'interaction à son terme.
Utilisez d'abord list_fin_capabilities pour trouver l'ID de la procédure pour l'action que vous souhaitez exécuter.
Entrées : procedure_id, user_id.