Hinweis
Der MCP-Server für die Fin Agent API befindet sich derzeit in der Beta-Phase und kann sich vor der endgültigen Veröffentlichung erheblich ändern. Ihr Feedback ist willkommen und hilft, die Zukunft dieses Produktfeatures zu gestalten.
Die Fin Agent API stellt einen entfernten Model Context Protocol (MCP)-Server bereit, der externen AI-Agenten ermöglicht, Fin als Werkzeug aufzurufen. Anstatt die Support-Logik in Ihrem eigenen Agenten neu zu erstellen, können Sie die Fin knowledge base, Verfahren und Multi-Turn-Konversationsfähigkeiten direkt aus jedem MCP-kompatiblen Client nutzen – einschließlich Claude, Claude Code, Cursor oder Ihrem eigenen Agenten-Framework.
Es gibt zwei Möglichkeiten zur Verbindung, abhängig davon, in welcher Rolle der Client agiert:
| Teammitglied | Endbenutzer |
URL | ||
Authentifiziert | Ein Workspace, über Fin Agent API api key | Ein einzelner, verifizierter Endbenutzer, über einen Messenger JWT |
Vertrauensmodell | Vertrauenswürdiges Server-zu-Server-Backend | Nicht vertrauenswürdiger pro Benutzer Client (ein AI-Assistent, der in oder nahe der Umgebung des Endbenutzers läuft) |
Wessen Identität? | Der Client gibt an, welcher Endbenutzer (user_id) bei jedem Aufruf vertreten ist | Das Token ist die Identität – der Client kann nicht als jemand anderes agieren |
Hält ein App-Level-Geheimnis? | Ja (der Fin Agent API key) | Nein – nur ein JWT, das auf einen Benutzer beschränkt ist |
Anwendungsfälle
Der Fin Agent API MCP-Server ist für Multi-Agent-Szenarien konzipiert, bei denen Ihr eigener Agent Zugriff auf die Fin-Fähigkeiten benötigt:
Eingebetteter Support in Produktagenten. Geben Sie dem AI-Assistenten Ihres Produkts die Möglichkeit, Supportfragen mit Ihrer konfigurierten Fin knowledge base zu beantworten, ohne Ihre knowledge base oder Inhalte zu duplizieren.
Verfahrensautomatisierung. Lassen Sie einen orchestrierenden Agenten Fin-Verfahren (Rückerstattungen, Upgrades, Kündigungen) im Namen von users auslösen und Multi-Turn-Interaktionen programmatisch steuern.
Fähigkeitsgesteuertes Routing. Verwenden Sie list_fin_capabilities, um zu bestimmen, welche Aktionen für einen bestimmten user verfügbar sind, und leiten Sie dann im Entscheidungslogik Ihres Agenten zum richtigen Werkzeug weiter.
Entwickler-Tools. Stellen Sie Ihre Fin knowledge base in Entwickler-Tools wie Claude Code oder Cursor bereit, damit interne users Ihre Supportinhalte aus ihrem bestehenden Workflow abfragen können.
Voraussetzungen
Ihr Intercom-Workspace muss die Fin Agent API-Funktion aktiviert haben. Kontaktieren Sie Ihr Intercom-Kontoteam, wenn Sie keinen Zugriff haben.
Endpunkte
Es gibt zwei Endpunkte, abhängig davon, wer die Anfrage stellt.
Teammitglied-Endpunkt
https://api.intercom.io/fin/mcp
Verwenden Sie diesen, wenn ein vertrauenswürdiger Backend-Dienst Fin im Namen eines users aufruft. Der Aufrufer authentifiziert sich mit einem OAuth-Zugriffstoken für den Workspace. Die Endbenutzer-Identität wird im Anfragetext vom aufrufenden Dienst bereitgestellt.
Dieses Modell ist für Server-zu-Server-Integrationen geeignet, bei denen Ihr Backend steuert, wer die Anfrage stellt.
Endbenutzer-Endpunkt
https://api.intercom.io/fin/mcp/{YOUR_APP_ID_CODE}Verwenden Sie diesen, wenn der MCP-Client in oder nahe der Umgebung des Endbenutzers läuft – zum Beispiel ein AI-Assistent, der lokal auf dem Gerät eines users läuft. Der Aufrufer authentifiziert sich mit einem signierten JWT, das einen einzelnen verifizierten Endbenutzer repräsentiert.
Der Pfadparameter {YOUR_APP_ID_CODE} ist Ihr Intercom-Workspace-Identifier (derselbe app_id, der in Messenger-Installations-Snippets verwendet wird).
Die Authentifizierung verwendet denselben Messenger-JWT-Mechanismus, der bereits für die Identitätsprüfung verwendet wird – wenn Sie die Messenger-Identitätsprüfung bereits eingerichtet haben, ist keine zusätzliche Konfiguration auf Intercom-Seite erforderlich.
Authentifizierung
Teammitglied-Endpunkt
Übergeben Sie Ihren Fin Agent API api key als Bearer-Token im Authorization-Header:
Authorization: Bearer YOUR_FIN_AGENT_API_KEY
Endbenutzer-Endpunkt
Generieren Sie ein signiertes JWT mit dem Messenger-Geheimnis Ihres Workspaces (zu finden unter Einstellungen → Sicherheit → Identitätsprüfung). Das JWT muss mit HS256 signiert sein und die externe ID des users im sub-Claim enthalten. Dies ist dasselbe JWT, das Sie zur Authentifizierung von Endbenutzern für den Messenger generieren würden.
Beispiel für JWT-Payload:
{
"user_id":"user@example.com"
}
Übergeben Sie es als Bearer-Token:
Authorization: Bearer YOUR_USER_JWT
Der im JWT identifizierte user ist der Nutzer, auf den Fin antworten wird. Fin verwendet diesen user, um Gespräche zu erstellen und Verfahren abzugleichen. Ihr Backend generiert dieses Token serverseitig und stellt es dem Client zur Verfügung – geben Sie Ihr Messenger-Geheimnis niemals clientseitig preis.
Verbindung von Claude
Claude Desktop
Fügen Sie Folgendes zu Ihrer claude_desktop_config.json hinzu:
Teammitglied-Endpunkt:
{
"mcpServers": {
"fin": {
"command": "npx",
"args": [
"-y",
"mcp-remote",
"https://api.intercom.io/fin/mcp",
"--header",
"Authorization: Bearer {YOUR_FIN_AGENT_API_KEY}"
}
}
}
}
Endbenutzer-Endpunkt:
{
"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)
Teammitglied-Endpunkt:
claude mcp add intercom-fin \
--transport http \
https://api.intercom.io/fin/mcp \
--header "Authorization: Bearer YOUR_FIN_AGENT_API_KEY"
Endbenutzer-Endpunkt:
claude mcp add intercom-fin \
--transport http \
https://api.intercom.io/fin/mcp/YOUR_APP_ID_CODE \
--header "Authorization: Bearer YOUR_USER_JWT"
Oder fügen Sie das entsprechende JSON zu .mcp.json unter mcpServers hinzu.
Werkzeuge
Sobald die Verbindung hergestellt ist, stellt der MCP-Server dem Client fünf Werkzeuge zur Verfügung.
list_fin_capabilities
Gibt die für einen bestimmten user verfügbaren Fin Agent API-Fähigkeiten zurück: die zielgruppengerechten Verfahren, die der user auslösen kann, sowie die statischen Aktionen, die allen users zur Verfügung stehen (eine Frage stellen, auf ein Gespräch antworten).
Rufen Sie dies zuerst auf, um herauszufinden, was Fin für einen bestimmten user tun kann, bevor Sie andere Werkzeuge aufrufen. Der Zugriff auf Verfahren ist zielgruppengerecht – nicht jeder user hat Zugriff auf jedes Verfahren.
Eingabe: user_id – die externe ID des users.
Gibt zurück: Ein JSON-Dokument mit einer Liste verfügbarer Fähigkeiten, jeweils mit Typ, ID und Name.
ask_fin
Sendet eine einmalige Frage an Fin und gibt eine Antwort zurück. Fin durchsucht Ihre konfigurierten knowledge sources und liefert eine direkte Antwort, ohne eine dauerhafte Konversation zu starten.
Verwenden Sie dies für Informationsabfragen, bei denen Sie eine direkte Antwort wünschen und keinen Multi-Turn-Flow benötigen.
Eingaben: user_id, message (die zu stellende Frage).
get_fin_response
Fragt die Antwort von Fin auf eine laufende Konversation oder einen Verfahrensablauf ab. Verwenden Sie dies, nachdem Sie eine Konversation oder ein Verfahren gestartet haben, um die neueste Antwort von Fin abzurufen.
Eingabe: conversation_id.
reply_to_fin_conversation
Sendet eine Folge-Nachricht in einer bestehenden Fin-Konversation. Verwenden Sie dies, um eine Multi-Turn-Interaktion fortzusetzen – zum Beispiel, um zusätzliche Informationen bereitzustellen, die Fin während eines Verfahrens angefordert hat.
Eingaben: conversation_id, message.
run_fin_procedure
Löst ein bestimmtes Fin-Verfahren für einen user aus. Ein Verfahren ist ein konfigurierter mehrstufiger Workflow – zum Beispiel die Bearbeitung einer Rückerstattung oder die Aktualisierung eines Abonnements. Fin startet das Verfahren, kann nach zusätzlichen Informationen fragen und steuert die Interaktion bis zum Abschluss.
Verwenden Sie list_fin_capabilities zuerst, um die Verfahrens-ID für die Aktion zu finden, die Sie ausführen möchten.
Eingaben: procedure_id, user_id.