Version: 2025.3.0

MCP Server

Generelle Informationen

Was ist ein MCP Server?

Ein MCP (Model Context Protocol) Server ist eine Schnittstelle, die es ermöglicht, mit Ihrem DocBee über standardisierte Tools zu kommunizieren. Der DocBee MCP Server fungiert als Brücke zwischen MCP-fähigen Clients (wie KI-Assistenten oder Automatisierungstools) und Ihrem DocBee.

Umfang

Der DocBee MCP Server bietet Zugriff auf verschiedene Funktionalitäten der DocBee-Plattform:

Ticket-Verwaltung: Erstellen, Aktualisieren und Abfragen von Tickets
Benutzeraktivitäten: Erstellen von Aktivitäten für Benutzer
Benachrichtigungen: Abrufen und Verwalten von Benachrichtigungen
Protokolle: Erstellen von Protokollen basierend auf Mustern

Alle Tools unterstützen die automatische Weiterleitung von Authentifizierungstokens und bieten eine vereinfachte Schnittstelle für die Interaktion mit Ihrem DocBee.

Wann sollten Sie einen MCP Server verwenden?

Ein MCP Server ist ideal für Sie, wenn Sie:

KI-Assistenten integrieren möchten: Nutzen Sie KI-Tools wie Claude, ChatGPT oder andere MCP-fähige Clients, um DocBee-Funktionen direkt aus dem Konversationskontext heraus zu nutzen
Automatisierung benötigen: Automatisieren Sie wiederkehrende Aufgaben wie das Erstellen von Tickets oder Aktivitäten
Einheitliche API-Schnittstelle wünschen: Nutzen Sie eine standardisierte Schnittstelle für verschiedene DocBee-Operationen
Vereinfachte Integration suchen: Vermeiden Sie die direkte Arbeit mit der DocBee REST API durch nutzerfreundliche Tools

Der MCP Server abstrahiert die Komplexität der DocBee API und bietet einfache, fokussierte Tools für häufige Aufgaben.

Einrichtung

Server-URL

Der DocBee MCP Server ist unter folgender URL erreichbar:

https://meine.docbee.url/mcp

Stellen Sie sicher, dass Sie diese URL in Ihrem MCP-Client konfigurieren.

Authentifizierung

Der DocBee MCP Server verwendet die Bearer Token-Authentifizierung. Jede Anfrage muss einen gültigen DocBee-Zugriffstoken im Authorization-Header enthalten.

Hinweis: Der MCP Server arbeitet mit der Berechtigung des Benutzers. Falls der Benutzer keine Berechtigung auf bestimmte Datensätze oder Funktionen hat, gilt dies auch für die MCP Schnittstelle.

So authentifizieren Sie sich

Token erhalten: Besorgen Sie sich einen gültigen DocBee-Zugriffstoken von Ihrem DocBee-Administrator oder über die DocBee-Benutzeroberfläche.
Token in Anfragen einbinden: Fügen Sie den Token im Authorization-Header jeder Anfrage hinzu:

Authorization: Bearer <ihr_docbee_zugriffstoken>

Token-Weiterleitung: Der MCP Server leitet den Token automatisch an die DocBee API weiter. Sie müssen sich keine Gedanken über die interne Token-Verarbeitung machen.

Beispiel-Anfrage

curl -X POST https://meine.docbee.url/mcp \
  -H "Authorization: Bearer IhrTokenHier" \
  -H "Content-Type: application/json" \
  -d '{
    "method": "tools/call",
    "params": {
      "name": "create_ticket",
      "arguments": {
        "description": "Neues Ticket erstellen"
      }
    }
  }'

Wichtig: Bewahren Sie Ihren Token sicher auf und teilen Sie ihn nicht mit Dritten. Ein kompromittierter Token kann zu unberechtigtem Zugriff auf Ihre DocBee-Daten führen.

Verfügbare Tools

Der DocBee MCP Server bietet die folgenden Tools für die Interaktion mit DocBee:

Ticket-Tools

`create_ticket`

Erstellt ein neues Ticket in DocBee.

Parameter:

description (erforderlich): Beschreibung des Tickets
priority (optional): Priorität als ID oder Name (z.B. "Hoch", "Niedrig")
ticket_status (optional): Ticket-Status als ID oder Name
customer (optional): Kunde als ID oder Name
customer_location (optional): Kundenstandort als ID oder Name
customer_contact (optional): Kundenkontakt als ID oder Name
owner (optional): Bearbeiter/Zuständiger als ID oder Name
ticket_category (optional): Ticket-Kategorie als ID oder Name
internal_description (optional): Interne Beschreibung
due_date (optional): Fälligkeitsdatum im ISO-Format (z.B. "2025-12-31T23:59:59Z")

Rückgabe:

id: Ticket-ID
ticketNumber: Ticket-Nummer (z.B. "V20250101-000001")
ticketStatus: Status-Name
priority: Prioritäts-Name
webLink: Link zum Ticket in DocBee

Beispiel:

{
  "name": "create_ticket",
  "arguments": {
    "description": "Server-Probleme beheben",
    "priority": "Hoch",
    "customer": "Acme Corp",
    "owner": "Max Mustermann"
  }
}

`update_ticket`

Aktualisiert ein bestehendes Ticket.

Parameter:

ticket (erforderlich): Ticket-ID oder Ticket-Nummer (z.B. "V20250101-000001")
description (optional): Neue Beschreibung
priority (optional): Neue Priorität als ID oder Name
ticket_status (optional): Neuer Status als ID oder Name
customer (optional): Kunde als ID oder Name
customer_location (optional): Neuer Standort als ID oder Name
customer_contact (optional): Neuer Kontakt als ID oder Name
owner (optional): Neuer Verantwortlicher als ID oder Name
ticket_category (optional): Neue Kategorie als ID oder Name
internal_description (optional): Neue interne Beschreibung
reference_number (optional): Referenznummer
external_reference_number (optional): Externe Referenznummer

Rückgabe:

id: Ticket-ID
ticketNumber: Ticket-Nummer
ticketStatus: Status-Name
priority: Prioritäts-Name
webLink: Link zum Ticket

Beispiel:

{
  "name": "update_ticket",
  "arguments": {
    "ticket": "V20250101-000001",
    "ticket_status": "In Bearbeitung",
    "priority": "Mittel"
  }
}

`get_ticket_by_number`

Ruft Details eines Tickets anhand der Ticket-Nummer ab.

Parameter:

ticket_number (erforderlich): Die Ticket-Nummer (z.B. "V20250101-000001")

Rückgabe:

ticketNumber: Ticket-Nummer
customer: Kundenname
description: Beschreibung
status: Status-Name
owner: Verantwortlicher
internalDescription: Interne Beschreibung
priority: Prioritäts-Name
dueDate: Fälligkeitsdatum
webLink: Link zum Ticket

Beispiel:

{
  "name": "get_ticket_by_number",
  "arguments": {
    "ticket_number": "V20250101-000001"
  }
}

`add_tags_to_ticket`

Fügt Tags zu einem Ticket hinzu.

Parameter:

ticket (erforderlich): Ticket-ID oder Ticket-Nummer
tags (erforderlich): Liste von Tag-IDs oder Tag-Namen

Rückgabe:

id: Ticket-ID
ticketNumber: Ticket-Nummer
tags: Aktualisierte Liste der Tags

Beispiel:

{
  "name": "add_tags_to_ticket",
  "arguments": {
    "ticket": "V20250101-000001",
    "tags": ["wichtig", "server"]
  }
}

`remove_tags_from_ticket`

Entfernt Tags von einem Ticket.

Parameter:

ticket (erforderlich): Ticket-ID oder Ticket-Nummer
tags (erforderlich): Liste von Tag-IDs oder Tag-Namen zum Entfernen

Rückgabe:

id: Ticket-ID
ticketNumber: Ticket-Nummer
tags: Aktualisierte Liste der Tags

Beispiel:

{
  "name": "remove_tags_from_ticket",
  "arguments": {
    "ticket": "V20250101-000001",
    "tags": ["wichtig"]
  }
}

Aktivitäten

`create_user_activity`

Erstellt eine neue Benutzeraktivität.

Parameter:

title (erforderlich): Titel der Aktivität
user (optional): Benutzer-ID (gegenseitig ausschließend mit user_phone_number und user_email)
user_phone_number (optional): Telefonnummer des Benutzers (gegenseitig ausschließend mit user und user_email)
user_email (optional): E-Mail-Adresse des Benutzers (gegenseitig ausschließend mit user und user_phone_number)
customer (optional): Kunde als ID oder Name
customer_location (optional): Kundenstandort als ID oder Name
customer_contact (optional): Kundenkontakt als ID oder Name (gegenseitig ausschließend mit contact_email und contact_phone_number)
contact_email (optional): Kontakt-E-Mail (gegenseitig ausschließend mit customer_contact und contact_phone_number)
contact_phone_number (optional): Kontakt-Telefonnummer (gegenseitig ausschließend mit customer_contact und contact_email)
description (optional): Beschreibung der Aktivität
url (optional): URL zur Aktivität
start_date (optional): Startdatum im ISO-Format
duration (optional): Dauer in Minuten
daily (optional): Ob die Aktivität täglich ist (Standard: false)
activity_type (optional): Typ der Aktivität - einer von: "DEFAULT", "PHONE", "ACTION", "INFO" (Standard: "DEFAULT")

Rückgabe:

id: Aktivitäts-ID
title: Titel der Aktivität
startDate: Startdatum

Beispiel:

{
  "name": "create_user_activity",
  "arguments": {
    "title": "Kundenanruf",
    "user": 123,
    "customer": "Acme Corp",
    "activity_type": "PHONE",
    "start_date": "2025-01-15T10:00:00Z",
    "duration": 30
  }
}

Benachrichtigungs-Tools

`get_unread_notifications`

Ruft alle ungelesenen Benachrichtigungen ab, sortiert nach Erstellungsdatum (älteste zuerst).

Parameter: Keine

Rückgabe:

notifications: Liste von Benachrichtigungen mit folgenden Feldern:
- id: Benachrichtigungs-ID
- createdDate: Erstellungsdatum
- content: Inhalt der Benachrichtigung
- subject: Betreff
- type: Typ der Benachrichtigung
- userProfileName: Name des Benutzerprofils
- senderUserName: Name des Absenders

Beispiel:

{
  "name": "get_unread_notifications",
  "arguments": {}
}

`mark_notification_read`

Markiert eine Benachrichtigung als gelesen.

Parameter:

notification_id (erforderlich): Die ID der Benachrichtigung

Rückgabe:

id: Benachrichtigungs-ID
tracked: Ob die Benachrichtigung als gelesen markiert wurde (true)

Beispiel:

{
  "name": "mark_notification_read",
  "arguments": {
    "notification_id": 456
  }
}

Protokoll-Tools

`create_protocol`

Erstellt ein neues Protokoll basierend auf einer Vorlage.

Parameter:

template (erforderlich): Protokollvorlage als Name oder ID
customer (erforderlich): Kunde als ID oder Name
customer_location (optional): Kundenstandort als ID oder Name
customer_contact (optional): Kundenkontakt als ID oder Name
person_in_charge (optional): Zuständige Person als ID oder Name

Rückgabe:

id: Protokoll-ID
protocolNumber: Protokoll-Nummer
protocolTemplate: Name der Vorlage mit Revisionsnummer (z.B. "Wartungsprotokoll - Rev. 1.0")
webLink: Link zum Protokoll in DocBee

Beispiel:

{
  "name": "create_protocol",
  "arguments": {
    "template": "Wartungsprotokoll",
    "customer": "Acme Corp",
    "customer_location": "Hauptstandort",
    "person_in_charge": "Max Mustermann"
  }
}

Meine Agenda Tools

`daily_schedule`

Ruft eine sortierte Liste von Terminplanungselementen für ein bestimmtes Datum ab, einschließlich Kalenderereignissen, Ticket-Fälligkeitsdaten und Ticket-Erinnerungen.

Parameter:

date (erforderlich): Datum im Format YYYY-MM-DD (z.B. "2025-01-15")

Rückgabe:

items: Liste von Terminplanungselementen, sortiert nach Startdatum (ganztägige Elemente zuerst, dann reguläre Elemente). Jedes Element enthält:
- id: Eindeutige ID des Elements
- color: Farbe des Elements
- title: Titel
- subTitle: Untertitel
- startDate: Startdatum und -zeit
- duration: Dauer in Minuten (falls vorhanden)
- allDay: Ob es sich um ein ganztägiges Ereignis handelt
- webLink: Link zum Element in DocBee
- customerData: Kundendaten (falls vorhanden)
- reasons: Liste der Gründe für das Element (z.B. ["calendar"], ["dueDate"], ["ticketReminder"])

Beispiel:

{
  "name": "daily_schedule",
  "arguments": {
    "date": "2025-01-15"
  }
}

FAQ

Was ist der Unterschied zwischen einem MCP Server und der direkten DocBee REST API?

Der MCP Server bietet eine vereinfachte, standardisierte Schnittstelle für häufige Aufgaben. Während die DocBee REST API sehr umfangreich ist, fokussiert sich der MCP Server auf die wichtigsten Funktionen und macht sie über einfache Tools zugänglich. Zudem unterstützt er die automatische Token-Weiterleitung und vereinfacht die Integration in MCP-fähige Clients.

Welche Clients können den DocBee MCP Server verwenden?

Jeder Client, der das Model Context Protocol (MCP) unterstützt, kann den Server verwenden. Dazu gehören verschiedene KI-Assistenten, Automatisierungstools und andere MCP-kompatible Anwendungen.

Wie sicher ist die Kommunikation mit dem MCP Server?

Der Server verwendet HTTPS für alle Kommunikationen und leitet Ihre Authentifizierungstokens sicher an die DocBee REST API weiter. Stellen Sie sicher, dass Sie immer HTTPS verwenden und Ihre Tokens sicher aufbewahren.

Wo bekomme ich einen DocBee-Zugriffstoken?

Sie können Ihren DocBee-Zugriffstoken direkt in der DocBee-Weboberfläche erstellen. Klicken Sie dazu oben rechts auf das Benutzer-Symbol und wählen Sie Einstellungen > Access Token. Dort können Sie einen neuen Token generieren lassen. Notieren Sie sich den Token sofort, da er nur einmal angezeigt wird.

Wichtig: Bewahren Sie Ihren Token sicher auf und teilen Sie ihn nicht mit Dritten. Ein kompromittierter Token kann zu unberechtigtem Zugriff auf Ihre DocBee-Daten führen.

Kann ich Tickets auch mit Nummer statt IDs angeben?

Ja, viele Parameter unterstützen sowohl IDs als auch Namen bzw. Nummern. Der Server versucht automatisch, Namen in IDs aufzulösen. Bei mehrdeutigen Namen sollten Sie jedoch die ID verwenden.

Wie finde ich die Ticket-Nummer eines Tickets?

Die Ticket-Nummer wird beim Erstellen eines Tickets zurückgegeben. Sie können auch die DocBee-Benutzeroberfläche verwenden, um die Ticket-Nummer zu finden. Das Format ist typischerweise "VYYYYMMDD-NNNNNN".

Ja, das tags-Parameter ist eine Liste, sodass Sie mehrere Tags gleichzeitig angeben können: ["tag1", "tag2", "tag3"].

Ich erhalte einen Authentifizierungsfehler. Was soll ich tun?

Überprüfen Sie:

Ob der Token korrekt im Authorization-Header steht
Ob der Token noch gültig ist
Ob der Token das Format Bearer <token> hat
Ob Sie HTTPS verwenden

Ein Tool gibt einen Fehler zurück, dass ein Feld nicht gefunden werden konnte. Was bedeutet das?

Dies bedeutet, dass der Server einen Namen (z.B. einen Kundennamen) nicht eindeutig in eine ID auflösen konnte. Versuchen Sie:

Den vollständigen, exakten Namen zu verwenden
Die ID direkt zu verwenden, falls verfügbar
Den Namen in der DocBee-Benutzeroberfläche zu überprüfen

Wie kann ich sehen, welche Parameter ein Tool erwartet?

Jedes Tool hat eine detaillierte Dokumentation in diesem Dokument. Die erforderlichen Parameter sind als "(erforderlich)" markiert, optionale Parameter als "(optional)".

Wieso erhalte ich eine Fehlermeldung?

Der MCP Server kann verschiedene HTTP-Status-Codes zurückgeben, die auf spezifische Probleme hinweisen. Hier sind einige häufige Codes und ihre Bedeutungen:

HTTP Status-Code	Beschreibung	Bedeutung
`429`	`Too many Requests`	Zu viele Anfragen in kurzer Zeit. Es dürfen nur eine bestimmte Anzahl von Aufrufen pro IP, Nutzer oder Global gemacht werden.
`401`	`Unauthorized`	Ungültige Authentifizierungsdaten, üerprüfen Sie Ihren Token.
`403`	`Forbidden`	Sie besitzen keine Berechtigung, die angeforderte Aktion auszuführen.

Generelle Informationen​

Was ist ein MCP Server?​

Umfang​

Wann sollten Sie einen MCP Server verwenden?​

Einrichtung​

Server-URL​

Authentifizierung​

So authentifizieren Sie sich​

Beispiel-Anfrage​

Verfügbare Tools​

Ticket-Tools​

create_ticket​

update_ticket​

get_ticket_by_number​

add_tags_to_ticket​

remove_tags_from_ticket​

Aktivitäten​

create_user_activity​

Benachrichtigungs-Tools​

get_unread_notifications​

mark_notification_read​

Protokoll-Tools​

create_protocol​

Meine Agenda Tools​

daily_schedule​

FAQ​

Was ist der Unterschied zwischen einem MCP Server und der direkten DocBee REST API?​

Welche Clients können den DocBee MCP Server verwenden?​

Wie sicher ist die Kommunikation mit dem MCP Server?​

Wo bekomme ich einen DocBee-Zugriffstoken?​

Kann ich Tickets auch mit Nummer statt IDs angeben?​

Wie finde ich die Ticket-Nummer eines Tickets?​

Ich erhalte einen Authentifizierungsfehler. Was soll ich tun?​

Ein Tool gibt einen Fehler zurück, dass ein Feld nicht gefunden werden konnte. Was bedeutet das?​

Wie kann ich sehen, welche Parameter ein Tool erwartet?​

Wieso erhalte ich eine Fehlermeldung?​

Generelle Informationen

Was ist ein MCP Server?

Umfang

Wann sollten Sie einen MCP Server verwenden?

Einrichtung

Server-URL

Authentifizierung

So authentifizieren Sie sich

Beispiel-Anfrage

Verfügbare Tools

Ticket-Tools

`create_ticket`

`update_ticket`

`get_ticket_by_number`

`add_tags_to_ticket`

`remove_tags_from_ticket`

Aktivitäten

`create_user_activity`

Benachrichtigungs-Tools

`get_unread_notifications`

`mark_notification_read`

Protokoll-Tools

`create_protocol`

Meine Agenda Tools

`daily_schedule`

FAQ

Was ist der Unterschied zwischen einem MCP Server und der direkten DocBee REST API?

Welche Clients können den DocBee MCP Server verwenden?

Wie sicher ist die Kommunikation mit dem MCP Server?

Wo bekomme ich einen DocBee-Zugriffstoken?

Kann ich Tickets auch mit Nummer statt IDs angeben?

Wie finde ich die Ticket-Nummer eines Tickets?

Ich erhalte einen Authentifizierungsfehler. Was soll ich tun?

Ein Tool gibt einen Fehler zurück, dass ein Feld nicht gefunden werden konnte. Was bedeutet das?

Wie kann ich sehen, welche Parameter ein Tool erwartet?

Wieso erhalte ich eine Fehlermeldung?