MCP-Plugins
Referenz für die MCP-Plugin-API zum Auflisten von Providern, Verwalten von Verbindungen und Abschließen von OAuth-Autorisierungen
curl "https://app.talkturo.com/api/mcp/providers" \
-H "Cookie: session=authenticated-session-cookie"
{
"providers": []
}
curl "https://app.talkturo.com/api/mcp/plugins?accountSlug=acme&assistantId=assistant-123" \
-H "Cookie: session=authenticated-session-cookie"
{
"plugins": [
{
"id": "close",
"name": "Close",
"description": "CRM integration",
"brandColor": "#1F8A70",
"iconUrl": null,
"authKind": "api_key",
"keyHelpUrl": null,
"connections": [
{
"id": "conn_a1b2c3d4",
"label": "Sales Close",
"expiresAt": null,
"needsReauth": false
}
],
"connectionId": "conn_a1b2c3d4",
"enabledTools": ["contacts.list"],
"defaultTools": ["contacts.list", "contacts.get"]
}
]
}
curl "https://app.talkturo.com/api/mcp/plugins/select" \
-X POST \
-H "Content-Type: application/json" \
-H "Cookie: session=authenticated-session-cookie" \
-d '{
"accountSlug": "acme",
"assistantId": "assistant-123",
"provider": "close",
"connectionId": "conn_a1b2c3d4",
"enabledTools": ["contacts.list"]
}'
{
"ok": true
}
curl "https://app.talkturo.com/api/mcp/plugins/tools?accountSlug=acme&provider=close" \
-H "Cookie: session=authenticated-session-cookie"
{
"tools": []
}
curl "https://app.talkturo.com/api/mcp/plugins/connect-key" \
-X POST \
-H "Content-Type: application/json" \
-H "Cookie: session=authenticated-session-cookie" \
-d '{
"accountSlug": "acme",
"provider": "close",
"apiKey": "dkai_example_9xmk7q2r",
"label": "Sales Close"
}'
{
"ok": true,
"connectionId": "conn_a1b2c3d4",
"label": "Sales Close"
}
curl "https://app.talkturo.com/api/mcp/oauth/authorize" \
-X POST \
-H "Content-Type: application/json" \
-H "Cookie: session=authenticated-session-cookie" \
-d '{
"provider": "calendly",
"accountSlug": "acme",
"label": "Calendly Sales"
}'
{
"url": "https://provider.example/authorize?response_type=code&client_id=client-example&redirect_uri=https%3A%2F%2Fapp.talkturo.com%2Fapi%2Fmcp%2Foauth%2Fcallback&state=oauth-state&code_challenge=challenge-value&code_challenge_method=S256"
}
curl "https://app.talkturo.com/api/mcp/oauth/callback?code=oauth-code&state=oauth-state" \
-H "Cookie: session=authenticated-session-cookie"
<!doctype html>
<html>
<body>
<script>
window.opener.postMessage({
type: "mcp_oauth_result",
ok: true,
provider: "calendly",
connectionId: "conn_a1b2c3d4",
at: 1710000000000
});
</script>
</body>
</html>
Endpunktübersicht
Die MCP-Plugin-API verwaltet Provider, Plugin-Verbindungen und verfügbare Tools für einen Workspace. Sie unterstützt API-Key-Verbindungen und OAuth-Autorisierungen.
| Methode | Endpunkt | Zweck |
|---|---|---|
GET | /api/mcp/providers | Verfügbare Provider abrufen |
GET | /api/mcp/plugins | Plugins und ihre Verbindungen abrufen |
POST | /api/mcp/plugins/select | Eine Verbindung oder Tools für ein Plugin auswählen |
GET | /api/mcp/plugins/tools | Tools eines Plugins abrufen |
POST | /api/mcp/plugins/connect-key | Eine Verbindung mit einem API-Key erstellen |
POST | /api/mcp/oauth/authorize | Eine OAuth-Autorisierungs-URL erstellen |
GET | /api/mcp/oauth/callback | OAuth-Callback verarbeiten |
Alle Endpunkte erfordern eine authentifizierte Session. Verwende die Session-Cookie des angemeldeten Workspaces für die Anfragen.
Provider auflisten
GET /api/mcp/providers
Ruft die MCP-Provider ab, die für die Plugin-Auswahl und Verbindung verfügbar sind.
Wenn der Endpunkt eine Workspace-Zuordnung unterstützt, identifiziert dieser Wert den Workspace. Verwende den in deiner Anwendung konfigurierten Workspace-Slug.
Fehlerverhalten
Der Endpunkt kann bei einer nicht authentifizierten Session oder einem fehlgeschlagenen Ladevorgang einen Fehler zurückgeben. Fehlerantworten enthalten ein error-Feld.
Plugins auflisten
GET /api/mcp/plugins
Ruft die Plugins eines Workspaces und deren gespeicherte Verbindungen ab. Wenn du assistantId angibst, berücksichtigt die Antwort die Konfiguration des zugehörigen Assistants.
Slug des Workspaces, für den die Plugins abgerufen werden.
Optionaler Assistant, dessen Plugin-Auswahl und aktivierte Tools berücksichtigt werden. Der Assistant muss zum angegebenen Workspace gehören.
Liste der für den Workspace verfügbaren Plugins.
Eindeutige Kennung des Providers.
Anzeigename des Plugins.
Beschreibung der Plugin-Integration.
Markenfarbe des Plugins.
URL zum Plugin-Symbol. Wenn kein Symbol vorhanden ist, ist der Wert null.
Authentifizierungsmethode des Providers.
URL mit Hinweisen zum Abrufen des API-Keys. Wenn keine Anleitung vorhanden ist, ist der Wert null.
Gespeicherte Verbindungen für das Plugin. Das Array kann leer sein.
Aktuell für den Assistant ausgewählte Verbindung. Der Wert ist null, wenn keine Verbindung ausgewählt ist.
Für den Assistant aktivierte Tools. Der Standardwert ist ein leeres Array.
Vom Provider konfigurierte Standard-Tools.
Eindeutige Kennung der Verbindung.
Anzeigename der Verbindung.
Ablaufzeit der Verbindung. Der Wert ist null, wenn keine Ablaufzeit festgelegt ist.
Gibt an, ob die Verbindung erneut autorisiert werden muss.
Die Antwort wird mit Cache-Control: no-store ausgeliefert. API-Keys und andere Zugangsdaten werden nicht in der Antwort zurückgegeben.
Plugin-Verbindung und Tools auswählen
POST /api/mcp/plugins/select
Wählt die Verbindung und die aktivierten Tools eines Plugins für einen Assistant aus.
Slug des Workspaces, für den die Auswahl gespeichert wird.
Kennung des Assistants, dessen Plugin-Konfiguration aktualisiert wird.
Kennung des Providers, für den die Auswahl gespeichert wird.
Kennung der zu verwendenden Verbindung. Verwende null, wenn keine Verbindung ausgewählt werden soll.
Liste der Tool-Kennungen, die für den Assistant aktiviert werden sollen.
Fehlerverhalten
Die API weist die Anfrage zurück, wenn der Workspace, der Assistant, der Provider oder die Verbindung nicht gefunden wird oder nicht zum authentifizierten Workspace gehört.
Plugin-Tools auflisten
GET /api/mcp/plugins/tools
Ruft die Tools eines MCP-Plugins ab. Verwende die zurückgegebenen Tool-Kennungen, um die Auswahl eines Assistants zu konfigurieren.
Slug des Workspaces, für den die Tools abgerufen werden.
Kennung des Providers, dessen Tools abgerufen werden.
Fehlerverhalten
Ein unbekannter Provider oder ein Workspace ohne Zugriff auf den Provider führt zu einer Fehlerantwort. Das Format der Fehlerantwort enthält ein error-Feld.
Verbindung mit einem API-Key erstellen
POST /api/mcp/plugins/connect-key
Erstellt eine Plugin-Verbindung mit einem API-Key. Der API-Key wird nicht in der Antwort zurückgegeben.
Slug des Workspaces, in dem die Verbindung gespeichert wird. Der Wert wird vor der Validierung von Leerzeichen am Anfang und Ende bereinigt.
Kennung des Providers. Der Wert wird vor der Validierung von Leerzeichen am Anfang und Ende bereinigt.
API-Key des Providers. Der Wert wird vor der Validierung von Leerzeichen am Anfang und Ende bereinigt.
Anzeigename der Verbindung. Wenn der Wert fehlt oder leer ist, wird automatisch ein Standardname erzeugt.
Gibt an, ob die Verbindung erfolgreich erstellt wurde.
Kennung der neu erstellten Verbindung.
Gespeicherter Anzeigename der Verbindung.
Der API-Key wird nur zur Verbindung mit dem Provider verwendet und nicht in der Antwort zurückgegeben. Übertrage API-Keys ausschließlich über HTTPS.
Mögliche Fehlerwerte
| Status | error |
|---|---|
401 | unauthorized |
400 | missing_params |
404 | unknown_provider |
404 | account_not_found |
403 | forbidden |
422 | no_tools |
422 | invalid_key |
502 | provider_unreachable |
500 | save_failed |
500 | connect_failed |
OAuth-Autorisierungs-URL erstellen
POST /api/mcp/oauth/authorize
Erstellt eine OAuth-Autorisierungs-URL für einen Provider. Öffne die zurückgegebene URL in einem Browserfenster, damit der Provider die Verbindung autorisieren kann.
Kennung des OAuth-Providers.
Slug des Workspaces, in dem die OAuth-Verbindung gespeichert wird.
Anzeigename der Verbindung. Der Wert wird von Leerzeichen am Anfang und Ende bereinigt und darf zwischen 1 und 80 Zeichen enthalten.
OAuth-Autorisierungs-URL des Providers. Die URL kann unter anderem response_type, client_id, redirect_uri, state, code_challenge und code_challenge_method enthalten.
Die OAuth-Autorisierungs-URL verwendet PKCE mit code_challenge_method=S256. Je nach Provider können zusätzlich scope oder resource enthalten sein.
Mögliche Fehlerwerte
| Status | error |
|---|---|
401 | unauthorized |
400 | invalid_body |
404 | unknown_provider |
404 | account_not_found |
403 | forbidden |
500 | authorize_failed |
Bei authorize_failed kann zusätzlich ein gekürztes detail-Feld mit maximal 300 Zeichen enthalten sein.
OAuth-Callback verarbeiten
GET /api/mcp/oauth/callback
Verarbeitet die Rückleitung des Providers nach einer OAuth-Autorisierung. Der Endpunkt gibt keine JSON-Antwort zurück, sondern eine HTML-Popup-Antwort, die das Ergebnis an das öffnende Fenster übermittelt.
OAuth-Code des Providers. Erforderlich, wenn der Provider keinen error-Parameter zurückgibt.
OAuth-State zur Validierung der Session. Erforderlich, wenn der Provider keinen error-Parameter zurückgibt.
Vom Provider zurückgegebener OAuth-Fehler. Wenn dieser Wert vorhanden ist, sind code und state nicht erforderlich.
Die Antwort hat den Content-Type text/html; charset=utf-8.
Typ der veröffentlichten Nutzdaten. Der Wert ist mcp_oauth_result.
Gibt an, ob die OAuth-Verbindung erfolgreich erstellt wurde.
Kennung des Providers bei einer erfolgreichen Autorisierung.
Kennung der gespeicherten Verbindung bei einer erfolgreichen Autorisierung.
Fehlerwert bei einer fehlgeschlagenen Autorisierung.
Zeitstempel, der beim Erstellen der veröffentlichten Nutzdaten mit Date.now() erzeugt wird.
Veröffentlichte Nutzdaten
Das Popup veröffentlicht das Ergebnis über drei Kanäle:
window.opener.postMessage(...)BroadcastChannel("talkturo:oauth-result")localStoragemit dem Schlüsseltalkturo:oauth-result
Eine erfolgreiche Autorisierung veröffentlicht Nutzdaten in diesem Format:
{
"type": "mcp_oauth_result",
"ok": true,
"provider": "calendly",
"connectionId": "conn_a1b2c3d4",
"at": 1710000000000
}
Eine fehlgeschlagene Autorisierung veröffentlicht Nutzdaten in diesem Format:
{
"type": "mcp_oauth_result",
"ok": false,
"error": "token_exchange_failed",
"at": 1710000000000
}
Mögliche Fehlerwerte
| Bedingung | error |
|---|---|
| Der Provider gibt einen OAuth-Fehler zurück | Vom Provider gelieferter Fehlerwert |
code oder state fehlt | missing_code_or_state |
| Session-Cookies fehlen | state_missing |
| Der State-Hash stimmt nicht überein | state_mismatch |
| Der serialisierte OAuth-Kontext ist ungültig | bad_context |
| Der Provider ist unbekannt | unknown_provider |
| Das konfigurierte Client-Secret fehlt | client_secret_missing |
| Der Token-Austausch schlägt fehl | token_exchange_failed |
| Das Speichern der Verbindung schlägt fehl | save_failed |
| Ein unerwarteter Fehler tritt auf | callback_failed |
Der OAuth-Callback kommuniziert ein JSON-förmiges Ergebnis an das öffnende Fenster, die HTTP-Antwort selbst ist jedoch HTML und nicht application/json.