RessourcenMCP-Plugins

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.

MethodeEndpunktZweck
GET/api/mcp/providersVerfügbare Provider abrufen
GET/api/mcp/pluginsPlugins und ihre Verbindungen abrufen
POST/api/mcp/plugins/selectEine Verbindung oder Tools für ein Plugin auswählen
GET/api/mcp/plugins/toolsTools eines Plugins abrufen
POST/api/mcp/plugins/connect-keyEine Verbindung mit einem API-Key erstellen
POST/api/mcp/oauth/authorizeEine OAuth-Autorisierungs-URL erstellen
GET/api/mcp/oauth/callbackOAuth-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.

query
accountSlugstring

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.

query
accountSlugstring
Required

Slug des Workspaces, für den die Plugins abgerufen werden.

query
assistantIdstring

Optionaler Assistant, dessen Plugin-Auswahl und aktivierte Tools berücksichtigt werden. Der Assistant muss zum angegebenen Workspace gehören.

pluginsarray
Required

Liste der für den Workspace verfügbaren Plugins.

idstring
Required

Eindeutige Kennung des Providers.

namestring
Required

Anzeigename des Plugins.

descriptionstring
Required

Beschreibung der Plugin-Integration.

brandColorstring
Required

Markenfarbe des Plugins.

iconUrlstring

URL zum Plugin-Symbol. Wenn kein Symbol vorhanden ist, ist der Wert null.

authKindstring
Required

Authentifizierungsmethode des Providers.

keyHelpUrlstring

URL mit Hinweisen zum Abrufen des API-Keys. Wenn keine Anleitung vorhanden ist, ist der Wert null.

connectionsarray
Required

Gespeicherte Verbindungen für das Plugin. Das Array kann leer sein.

connectionIdstring

Aktuell für den Assistant ausgewählte Verbindung. Der Wert ist null, wenn keine Verbindung ausgewählt ist.

enabledToolsarray
Required

Für den Assistant aktivierte Tools. Der Standardwert ist ein leeres Array.

defaultToolsarray
Required

Vom Provider konfigurierte Standard-Tools.

idstring
Required

Eindeutige Kennung der Verbindung.

labelstring
Required

Anzeigename der Verbindung.

expiresAtstring

Ablaufzeit der Verbindung. Der Wert ist null, wenn keine Ablaufzeit festgelegt ist.

needsReauthboolean
Required

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.

body
accountSlugstring
Required

Slug des Workspaces, für den die Auswahl gespeichert wird.

body
assistantIdstring
Required

Kennung des Assistants, dessen Plugin-Konfiguration aktualisiert wird.

body
providerstring
Required

Kennung des Providers, für den die Auswahl gespeichert wird.

body
connectionIdstring

Kennung der zu verwendenden Verbindung. Verwende null, wenn keine Verbindung ausgewählt werden soll.

body
enabledToolsarray

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.

query
accountSlugstring
Required

Slug des Workspaces, für den die Tools abgerufen werden.

query
providerstring
Required

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.

body
accountSlugstring
Required

Slug des Workspaces, in dem die Verbindung gespeichert wird. Der Wert wird vor der Validierung von Leerzeichen am Anfang und Ende bereinigt.

body
providerstring
Required

Kennung des Providers. Der Wert wird vor der Validierung von Leerzeichen am Anfang und Ende bereinigt.

body
apiKeystring
Required

API-Key des Providers. Der Wert wird vor der Validierung von Leerzeichen am Anfang und Ende bereinigt.

body
labelstring

Anzeigename der Verbindung. Wenn der Wert fehlt oder leer ist, wird automatisch ein Standardname erzeugt.

okboolean
Required

Gibt an, ob die Verbindung erfolgreich erstellt wurde.

connectionIdstring
Required

Kennung der neu erstellten Verbindung.

labelstring
Required

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

Statuserror
401unauthorized
400missing_params
404unknown_provider
404account_not_found
403forbidden
422no_tools
422invalid_key
502provider_unreachable
500save_failed
500connect_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.

body
providerstring
Required

Kennung des OAuth-Providers.

body
accountSlugstring
Required

Slug des Workspaces, in dem die OAuth-Verbindung gespeichert wird.

body
labelstring

Anzeigename der Verbindung. Der Wert wird von Leerzeichen am Anfang und Ende bereinigt und darf zwischen 1 und 80 Zeichen enthalten.

urlstring
Required

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

Statuserror
401unauthorized
400invalid_body
404unknown_provider
404account_not_found
403forbidden
500authorize_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.

query
codestring

OAuth-Code des Providers. Erforderlich, wenn der Provider keinen error-Parameter zurückgibt.

query
statestring

OAuth-State zur Validierung der Session. Erforderlich, wenn der Provider keinen error-Parameter zurückgibt.

query
errorstring

Vom Provider zurückgegebener OAuth-Fehler. Wenn dieser Wert vorhanden ist, sind code und state nicht erforderlich.

Content-Typestring
Required

Die Antwort hat den Content-Type text/html; charset=utf-8.

typestring
Required

Typ der veröffentlichten Nutzdaten. Der Wert ist mcp_oauth_result.

okboolean
Required

Gibt an, ob die OAuth-Verbindung erfolgreich erstellt wurde.

providerstring

Kennung des Providers bei einer erfolgreichen Autorisierung.

connectionIdstring

Kennung der gespeicherten Verbindung bei einer erfolgreichen Autorisierung.

errorstring

Fehlerwert bei einer fehlgeschlagenen Autorisierung.

atnumber
Required

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")
  • localStorage mit dem Schlüssel talkturo: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

Bedingungerror
Der Provider gibt einen OAuth-Fehler zurückVom Provider gelieferter Fehlerwert
code oder state fehltmissing_code_or_state
Session-Cookies fehlenstate_missing
Der State-Hash stimmt nicht übereinstate_mismatch
Der serialisierte OAuth-Kontext ist ungültigbad_context
Der Provider ist unbekanntunknown_provider
Das konfigurierte Client-Secret fehltclient_secret_missing
Der Token-Austausch schlägt fehltoken_exchange_failed
Das Speichern der Verbindung schlägt fehlsave_failed
Ein unerwarteter Fehler tritt aufcallback_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.

Verwandte Ressourcen