Nuvoca mit deinem KI-Assistenten verbinden¶

Verbinde Nuvoca als MCP-Server mit deinem KI-Assistenten. Danach kannst du in natürlicher Sprache Agents erstellen, Prompts prüfen und gespeicherte Anrufzusammenfassungen auswerten. Du entscheidest bei der Anmeldung, welche Rechte du freigibst.

Diese Anleitung betrifft die Verwaltung deines Nuvoca-Workspaces aus einem KI-Assistenten. Wenn dein Voice Agent während eines Anrufs einen externen MCP-Dienst nutzen soll, folge MCP-Tools verbinden.

Voraussetzungen¶

Ein Nuvoca-Konto mit Zugriff auf den gewünschten Workspace.
Einen MCP-Client mit Streamable HTTP, OAuth Authorization Code mit PKCE S256 und Unterstützung für Client ID Metadata Documents (CIMD) oder eine manuell registrierte öffentliche OAuth-Anwendung.
Die passenden Rechte für deine Aufgabe im gewünschten Workspace.

Die verfügbaren Verbindungsoptionen hängen von Client, Version und Nuvoca-Umgebung ab. Ein Client, der ausschließlich automatische dynamische Registrierung (DCR) verlangt, kann diesen Zugang nicht nutzen.

1. MCP-URL übernehmen¶

Verwende diese URL, um deinen KI-Assistenten mit Nuvoca zu verbinden:

https://app.nuvoca.ai/mcp

Du findest sie auch unter Einstellungen → API-Zugriff → Verbindungen → Über MCP verbinden. Wenn du eine separate Nuvoca-Umgebung nutzt, übernimm deren dort angezeigte MCP URL. Die Verwaltung von API-Zugriffen benötigt entsprechende Administratorrechte.

2. Verbindung im KI-Assistenten hinzufügen¶

Öffne die MCP- oder Connector-Einstellungen deines Assistenten.
Füge einen entfernten Server mit dem Namen Nuvoca und der kopierten URL hinzu.
Wähle OAuth und starte die Verbindung. Melde dich im geöffneten Browser bei Nuvoca an und schließe gegebenenfalls deine MFA-Anmeldung ab.
Prüfe Clientname, Workspace und angefragte Rechte. Bei einer Workspace-Auswahl wähle den vorgesehenen Workspace.
Gib nur die für deinen Auftrag benötigten Rechte frei und kehre zum Assistenten zurück.

Bei CIMD-fähigen Clients wird die Softwareidentität über deren Metadaten erkannt. Verlangt dein Client eine manuelle Client-ID, muss ein Administrator eine OAuth-Anwendung registrieren. Die Callback-URL muss genau zum Client passen; die manuelle Registrierung akzeptiert HTTPS-Callbacks. Der Client muss die Autorisierung für die MCP-Resource durchführen.

Der MCP-Zugang nutzt OAuth. Ein REST-API-Schlüssel oder REST-Access-Token kann hier nicht als Ersatz eingesetzt werden. Agent Studio ergänzt die Arbeitsanleitungen und wird separat installiert.

Verbindung im Terminal einrichten¶

Diese Befehle verbinden deinen Client mit https://app.nuvoca.ai/mcp. Prüfe die Rechte im anschließenden Browserdialog. Für eine separate Nuvoca-Umgebung ersetzt du die URL durch deren MCP-Adresse.

Codex CLIClaude Code

codex mcp add nuvoca --url "https://app.nuvoca.ai/mcp"
codex mcp login nuvoca --scopes connection:verify,agents:read

Der Login-Befehl fordert Rechte für einen ersten Lesetest an. Für weitere Aufgaben autorisierst du die benötigten Scopes erneut. Öffne danach einen neuen Chat. Siehe auch die offizielle Codex-MCP-Anleitung.

claude mcp add --transport http nuvoca "https://app.nuvoca.ai/mcp"
claude mcp login nuvoca

Alternativ öffnest du in einer interaktiven Sitzung /mcp und meldest dich dort an. Verwende eine Version mit CIMD-Unterstützung. Siehe die offizielle Claude-Code-MCP-Anleitung.

3. Workspace und Tools prüfen¶

Prüfe mit verify_connection den verbundenen Nuvoca-Workspace und die
freigegebenen Rechte. Liste danach meine Agents mit list_agents auf.
Ändere noch nichts.

verify_connection benötigt connection:verify, list_agents benötigt agents:read. Die Prüfung liefert Workspace-Name, ID und Scopes. Eine Verbindung ist an genau diesen Workspace gebunden. Für einen anderen Workspace startest du eine weitere Autorisierung.

Rechte passend zum Auftrag wählen¶

Auftrag	Benötigte Scopes
Verbindung prüfen und Agents auflisten	`connection:verify`, `agents:read`
Prompts und Agent-Einstellungen prüfen	zusätzlich `agents:configuration:read`
Agents erstellen oder ändern	zusätzlich `agents:write`
Agentic Flows lesen und konfigurieren	`flows:read`, `flows:write`; für die Agent-Auswahl auch `agents:read`
Tools lesen und konfigurieren	`tools:read`, `tools:write`
Knowledge Bases und Dokumente verwalten	`knowledge-bases:read`, `knowledge-bases:write`, `documents:read`, `documents:write`
Heutige Zusammenfassungen auswerten	`call-summaries:read`; empfohlen auch `connection:verify`
Vorhandene Rufnummern zuweisen	`phone-numbers:read`, `phone-numbers:write`

Lese- und Schreibrechte sind getrennt. Scopes erweitern deine Rolle nicht. Bestehende Freigaben erhalten neue Scopes erst durch eine neue Autorisierung. Die vollständigen MCP-Tools und Scopes sind in der Referenz beschrieben.

Änderungen prüfen und testen¶

Lass den Assistenten vor einer Änderung Katalog und aktuelle Konfiguration lesen. Prüfe Agent, Prompt, Stimme und geplante Tool-Aktionen. Neue Agents kannst du deaktiviert und ohne Rufnummer vorbereiten; bestehende Agents werden direkt geändert, wenn du einen Schreibauftrag ausführst.

Eine Rufnummernzuweisung ändert das Routing. Das Speichern einer Konfiguration führt keinen Testanruf aus. Prüfe neue Konfigurationen mit einem Testanruf. Drei kopierbare Beispiel-Prompts unterstützen diesen Ablauf.

Zugriff erneuern oder widerrufen¶

Access-Token gelten fünf Minuten. Der Client kann sie mit rotierenden Refresh-Token innerhalb einer maximal 24-stündigen Freigabe erneuern. Danach oder nach einem Widerruf verbindest du dich erneut.

Unter API-Zugriff → Verbindungen → Meine Freigaben siehst und widerrufst du deine eigenen Autorisierungen. Administratoren mit den nötigen Rechten können unter MCP im Tenant die aktiven MCP-Freigaben ihres Workspaces verwalten. Eine aufgeführte Freigabe bedeutet nicht, dass der Client gerade online ist.

Verbindung beheben¶

Problem	Nächster Schritt
MCP-URL fehlt oder OAuth ist nicht verfügbar	Workspace-Administrator um Prüfung der Umgebung bitten.
Anmeldung klappt, ein Tool fehlt	Scopes der Freigabe prüfen; für zusätzliche Rechte erneut autorisieren und Katalog neu laden.
`FORBIDDEN` trotz sichtbarem Tool	Aktuelle Rolle und Zugriff auf den Workspace prüfen.
`CONFLICT` beim Speichern	Aktuellen Stand erneut lesen und Vorschlag abgleichen.
Ergebnis einer Erstellung unklar	Vor erneutem Anlegen vorhandene Ressourcen prüfen.
HTTP `429`	Die in `Retry-After` angegebene Zeit abwarten.
Client verlangt einen API-Schlüssel oder DCR	OAuth-/CIMD-Unterstützung beziehungsweise manuelle Registrierung prüfen.