GREYHOUND Docs Entwickler

MCP-Server

In GREYHOUND ist ein rudimentärer Model Context Protocol Server (MCP-Server) integriert. Über das MCP-Protokoll können sich externe Agenten und Tools mit GREYHOUND verbinden und die vorhandenen Endpunkte aufrufen.

Typische Anwendungsfälle sind die Integration von GREYHOUND in Automatisierungs- oder Agenten-Frameworks sowie in MCP-kompatible Entwicklungsumgebungen, z. B. n8n, Cursor AI, Claude Code oder andere MCP-kompatible Clients.

Der MCP-Server stellt die bestehenden GREYHOUND-RPC-Funktionen strukturiert als MCP-Tools zur Verfügung.

Spezifikationen

Die offizielle MCP-Spezifikation ist zu finden unter: https://modelcontextprotocol.io

Der GREYHOUND-MCP-Server arbeitet nach folgenden Prinzipien:

• Jede RPC-Methode des GREYHOUND-Servers wird 1:1 als eigenes MCP-Tool bereitgestellt.
• Es erfolgt keine zusätzliche Abstraktions- oder Business-Logik auf MCP-Ebene.
• Die Berechtigungen entsprechen denen des verwendeten GREYHOUND-Benutzers.

Voraussetzungen

Für die Nutzung des MCP-Servers werden benötigt:

• GREYHOUND ab Version 5.6.28 build 5098
• Zugriff auf den GREYHOUND-Server über HTTP oder HTTPS (HTTPS wird empfohlen)
• Ein gültiger API-Token
• Ein MCP-kompatibler Client

Authentifizierung

Für jeden Zugriff auf den MCP-Server wird ein API-Token benötigt, der im Authorization-Header übergeben wird.

Authorization: Bearer <token>

Hinweis: Der MCP-Server unterstützt ausschließlich die Authentifizierung per Bearer-Token. Die bei der GREYHOUND-RPC-API verwendete Basic-Authentifizierung wird vom MCP-Server nicht unterstützt.

Der API-Token besitzt dieselben Berechtigungen wie der zugehörige GREYHOUND-Benutzer.

Sidenote: GREYHOUND unterstützt zwei Auth-Verfahren: Bearer-Token (wird direkt im Authorization-Header übergeben) und Basic-Auth (Base64-kodiert aus [ClientID]-[Username]:[Passwort]). Für MCP verwenden wir den Bearer-Token, NICHT Basic-Auth. 

API-Token erstellen

Ein API-Token kann wie folgt im GREYHOUND Windows-Client erstellt werden:

1. Zu Einstellungen > Mein Benutzerkonto navigieren.
2. Zum Reiter API-Token wechseln.
3. “Neuen API-Token erstellen” auswählen.
4. Einen beliebigen Anwendungsnamen vergeben.
5. Den erzeugten Token kopieren.

Empfehlung: Für die Integrationen sollte ein separater API-Benutzer mit nur den tatsächlich benötigten Berechtigungen verwendet werden.

Eine detaillierte Anleitung, wie man einen gültigen Authentifizierungs-Token erstellt, befindet sich hier im Handbuch.

Basis-URL

Der MCP-Server ist standardmäßig unter folgender URL erreichbar:

https://<ServerUrl>/mcp

Über diese URL können…

• alle verfügbaren MCP-Tools geladen,
• Metadaten der bereitgestellten RPC-Methoden abgefragt und
• sämtliche Tool-Aufrufe ausgeführt werden.

Für produktive Umgebungen wird die Verwendung von HTTPS mit einem gültigen SSL-Zertifikat empfohlen.

Tool-Struktur und Performance

Standardmäßig werden beim Zugriff auf den Endpunkt /mcp sämtliche verfügbaren RPC-Methoden als MCP-Tools bereitgestellt.

Zur Verbesserung der Initialisierungszeit und zur Reduzierung der Anzahl bereitgestellter Tools können einzelne RPC-Klassen gezielt geladen werden.

Einzelne RPC-Klasse laden

Hierzu wird der Klassenname an die Basis-URL angehängt:

https://<ServerUrl>/mcp/<RpcClassName>

Beispiel:

https://<ServerUrl>/mcp/RpcInfoLib

In diesem Fall werden ausschließlich die Methoden der Klasse RpcInfoLib als MCP-Tools bereitgestellt.

Diese Variante empfiehlt sich insbesondere für:

• Agenten mit engem Funktionsumfang
• performanzkritische Integrationen
• Entwicklungs- und Testumgebungen

Häufige Fehler

Bei Verbindungsproblemen sollten insbesondere folgende Punkte überprüft werden:

• Die URL verwendet den korrekten Pfad /mcp und nutzt https://
  • Beispiel: https://greyhound.meinefirma.de/mcp  
• Der API-Token ist gültig und besitzt die erforderlichen Berechtigungen.
• Es wird ein Bearer-Token verwendet.
• Das SSL-Zertifikat wird vom Client akzeptiert.
• Die Datei .mcp.json befindet sich im Projektverzeichnis.
• Die projektbezogenen MCP-Server wurden aktiviert.
• Falls nur eine RPC-Klasse verwendet wird, ist deren Name korrekt angegeben.

Allgemeine Sicherheitshinweise

API-Tokens sollten wie Passwörter behandelt werden.

Wir empfehlen:

• API-Tokens nicht in öffentlichen Repositories oder gemeinsam genutzten Konfigurationsdateien zu speichern.
• Einen separaten API-Benutzer für Integrationen zu verwenden.
• Dem API-Benutzer ausschließlich die tatsächlich benötigten Berechtigungen zuzuweisen (Least Privilege).
• API-Tokens sollten nicht an Dritte weitergegeben werden.

ACHTUNG: Wer Claude Code nutzt, sollte wissen, dass die .mcp.json den Bearer-Token enthält! Wer Git verwendet, muss .mcp.json unbedingt zu.gitignore hinzufügen, damit der Token nicht versehentlich in ein Repository gepusht wird!

Verwendung mit Claude Code (Beispiel)

Claude Code unterstützt die direkte Einbindung externer MCP-Server.

1. Überblick & Voraussetzungen

Das Model Context Protocol (MCP) ermöglicht es Claude Code, direkt mit Ihrem Greyhound-Server zu kommunizieren.  
Claude kann dann E-Mails lesen, beantworten, Textbausteine abrufen, Kontakte verwalten und vieles mehr – alles über eine sichere, verschlüsselte Verbindung.  

Voraussetzungen

• macOS, Linux oder Windows mit Windows Subsystem for Linux
• Claude Code ist installiert (Anthropic CLI)
• GREYHOUND ist über HTTP oder HTTPS erreichbar (HTTPS empfohlen)
• es liegt ein gültiger API-Token vor
• es besteht Zugang zum GREYHOUND Control Center (GCC) für die SSL-Konfiguration  
• IP des GREYHOUND-Servers ist bekannt (zu finden im GCC unter Verträge > Hosting-Paket)
• es existiert eine eigene Domain oder Subdomain (z.B. greyhound.meinefirma.de)  
• es liegt der Zugang zum DNS-Provider vor (z. B. Strato, IONOS, Hetzner, Cloudflare)

Wie die Verbindung funktioniert  

Claude Code verbindet sich über HTTPS (Port 443) mit dem GREYHOUND-Server. Die Authentifizierung erfolgt über einen Bearer-Token, der in GREYHOUND zu erstellen ist. Die Verbindung ist Ende-zu-Ende verschlüsselt mittels SSL/TLS. 

Gut zu wissen  

GREYHOUND nutzt zwei verschiedene Ports:  

• Port 9000: Proprietäres RPCP-Protokoll (für den GREYHOUND-Client)  
• Port 443: HTTPS für JSON-RPC, MCP und Web-Zugriff  

Für MCP benötigen wir ausschließlich Port 443 (HTTPS)! 

2. DNS-Subdomain einrichten 

Damit ein gültiges SSL-Zertifikat ausgestellt werden kann, benötigt der GREYHOUND-Server einen DNS-Namen (eine Subdomain). Eine reine IP-Adresse reicht nicht, da Let’s Encrypt keine Zertifikate für IPs ausstellt.  

Schritt für Schritt Anleitung

1. Login beim DNS-Provider (z. B. Strato, IONOS, Hetzner, Cloudflare). 
2. Anlegen eines neuen A-Records, wie folgt:
   • Name/Subdomain: z. B. greyhound (ergibt greyhound.meinefirma.de)  
   • Typ: A  
   • Ziel/Wert: Die IP-Adresse des GREYHOUND-Servers  
   • TTL: Standard (z. B. 3600 oder 300)  
3. DNS-Eintrag speichern. Die Änderung kann je nach Provider wenige Minuten bis zu 24 Stunden dauern.  

Überprüfen  

Öffne ein Terminal und prüfe mit folgendem Befehl:  

dig +short greyhound.meinefirma.de A  

Der Befehl sollte die IP-Adresse des GREYHOUND-Servers zurückgeben. Wenn keine Antwort kommt, bitte etwas warten und erneut versuchen.  

3. SSL-Zertifikat im GCC konfigurieren  

Das GREYHOUND Control Center (GCC) ist das Admin-Panel für den GREYHOUND-Server. Dort sind der externe Hostnamen und das SSL-Zertifikat zu konfigurieren.

Schritt für Schritt Anleitung

1. Im GCC navigieren zu Verträge > Hosting-Paket.
2. Unter “Externer Hostname” die neue Subdomain eintragen: greyhound.meinefirma.de  
3. Bei “SSL-Zertifikat” die Option “Let’s Encrypt Zertifikat automatisch generieren” auswählen.
4. Bei “Serverkomponenten” die Option “Alle Serverkomponenten” wählen.
5. Eine gültige E-Mail-Adresse eintragen für Let’s Encrypt Benachrichtigungen.
6. Speichern.

Port 80 muss erreichbar sein!  
Let’s Encrypt validiert das Zertifikat über Port 80 (HTTP). Falls die Validierung fehlschlägt, ist der Hosting-Provider zu kontaktieren mit der Bitte, Port 80 für die ACME-Validierung freizugeben. Für Kunden, die das GREYHOUND-Hosting nutzen, ist dies normalerweise bereits der Fall.  

Überprüfen  

Nach einigen Minuten kann das Zertifikat geprüft werden:

echo | openssl s_client -connect greyhound.meinefirma.de:443 \ -servername greyhound.meinefirma.de 2>/dev/null | \ openssl x509 -noout -issuer -dates  

In der Ausgabe sollte “Let’s Encrypt” als Issuer erscheinen und das Zertifikat sollte gültig sein.  

Kein eigenes Zertifikat nötig  
Let’s Encrypt stellt kostenlose, automatisch erneuerte Zertifikate aus. Es ist nicht nötig, ein eigenes Zertifikat zu kaufen oder manuell zu installieren. GREYHOUND kümmert sich um die automatische Erneuerung. 

4. API-Benutzer & Bearer-Token anlegen

Claude Code authentifiziert sich gegenüber GREYHOUND mit einem Bearer-Token. Dafür ist in GREYHOUND ein eigener Benutzer für den API-Zugriff anzulegen. Das geht wie folgt:

Benutzer anlegen  

1. In GREYHOUND zu Einstellungen > Benutzerverwaltung navigieren.
2. Einen neuen Benutzer anlegen und als Benutzername z. B. “ghapi” wählen sowie als Anzeigename “API-Benutzer”.
3. Ein sicheres Passwort vergeben.
4. Dem Benutzer die nötigen Rechte zuweisen. Empfehlung für den Start:  
   • Items lesen und bearbeiten  
   • Textbausteine lesen  
   • Gruppen, Themen, Farben lesen  
   • Signaturen und Templates lesen  

Tipp: Bitte sparsam sein mit den Rechten! Es sollten nur die Rechte erteilt werden, die Claude tatsächlich braucht.  

Bearer-Token generieren 

Der Bearer-Token wird aus der Client-ID und den Zugangsdaten generiert. GREYHOUND stellt hierfür eine Authentifizierungs-Schnittstelle bereit.  An den Token kommt man wie folgt:

1. In GREYHOUND zu Einstellungen > Mein Benutzerkonto navigieren.
2. Zum Reiter “API-Token” gehen.
3. Auf “Neuen API-Token erstellen” klicken.
4. Einen beliebigen Anwendungsname festlegen (z. B. Claude). 
5. Token in Zwischenablage kopieren durch Klick auf das Icon rechts.
6. Fenster mit OK schließen.

5. Claude Code installieren und Projekt anlegen  

Claude Code ist Anthropics offizielle Kommandozeilen-Anwendung (CLI). Es ist zu installieren über npm (Node.js Package Manager).

Installation  

1. Es ist sicherzustellen, dass Node.js (Version 18+) installiert ist:  
   node --version  

2. Danach ist Claude Code global zu installieren:  
   npm install -g @anthropic-ai/claude-code  

3. Anschließend kann Claude Code zum ersten Mal gestartet werden und man kann sich anmelden:  
   claude  

Es ist den Anweisungen zur Anmeldung mit dem persönlichen Anthropic-Konto zu folgen.

Projektverzeichnis anlegen  

1. Erstellen eines Verzeichnisses für das GREYHOUND-Projekt:  
   mkdir ~/greyhound-projekt  
cd ~/greyhound-projekt  

2. Optional: Initialisieren eines Git-Repository (empfohlen):  
   git init 

6. MCP-Konfiguration erstellen (.mcp.json)  

Die zentrale Konfigurationsdatei für MCP-Server heißt .mcp.json und liegt im Wurzelverzeichnis des Projekts.  

Datei erstellen  

Die Datei .mcp.json ist im Projektverzeichnis mit folgendem Inhalt zu erstellen:

{  
"mcpServers": {  
     "greyhound": {  
             "type": "http",  
	      "url": "https://greyhound.meinefirma.de/mcp",  
	      "headers": {  
		"Authorization": "Bearer IHR_TOKEN_HIER"  
	       }  
          }  
     }  
}  

Erklärung der einzelnen Felder:

• “type“: “http” – Claude verbindet sich per HTTP/HTTPS (nicht stdio)  
• “url” – Die vollständige URL zum GREYHOUND MCP-Endpunkt. Pfad muss auf /mcp enden! 
• “headers” – HTTP-Header, hier der Authorization-Header mit dem Bearer-Token 

ACHTUNG: Die .mcp.json enthält den Bearer-Token! Wer Git verwendet, muss .mcp.json unbedingt zu .gitignore hinzufügen, damit der Token nicht versehentlich in ein Repository gepusht wird!

7. Claude Code Settings konfigurieren  

Claude Code muss wissen, dass es den MCP-Server aus der .mcp.json verwenden soll. Dafür passt man die lokalen Projekteinstellungen wie folgt an.

settings.local.json bearbeiten  

Die Datei liegt unter .claude/settings.local.json im Projektverzeichnis. Falls diese noch nicht existiert, ist die wie folgt zu erstellen:

{  
         "enableAllProjectMcpServers": true  
} 

Diese Einstellung aktiviert alle MCP-Server, die in der .mcp.json definiert sind.  

Alternative: Einzelne Server aktivieren  

Wer sich mehr Kontrolle wünscht, kann auch gezielt einzelne Server aktivieren:  

{  
	"enableAllProjectMcpServers": false,  
	"enabledMcpjsonServers": ["greyhound"]  
}  

Keine SSL-Workarounds nötig

Mit einem gültigen Let’s Encrypt Zertifikat benötigt man KEINE der folgenden Umgebungsvariablen (und sollte sie auch NICHT setzen!):  

• NODE_TLS_REJECT_UNAUTHORIZED=0 (unsicher! deaktiviert SSL-Prüfung)  
• NODE_EXTRA_CA_CERTS (nur bei selbstsignierten Zertifikaten)  

Falls diese Variablen irgendwo gesetzt sind, müssen diese entfernt werden. 

8. Verbindung testen  

Jetzt sollten wir die Verbindung wie folgt testen:

1. Terminal öffnen und zum Projektverzeichnis navigieren:
   cd ~/greyhound-projekt  
2. Claude Code starten:
   claude  
3. MCP-Status mit dem folgenden Befehl prüfen:
   /mcp
4. In der Ausgabe sollte “greyhound” als “connected” erscheinen. Wenn der Status connected ist, dann funktioniert die Verbindung.
5. Probieren wir es doch mal mit einem einfachen Befehl, z. B.: 
   Frage Claude: “Zeige mir die GREYHOUND-Server-Info”.  

Claude wird die RpcInfo_GetServerInfo-Methode aufrufen und die Server-Version, Lizenzinfos und weitere Details anzeigen. 

Erfolgreiche Verbindung erkennen  

• Status „connected“ bei /mcp 
• Claude kann GREYHOUND-Befehle ausführen (z. B. Server-Info abrufen)  
• Keine SSL- oder Authentifizierungsfehler in der Ausgabe 

9. Häufige Fehler und Lösungen  

10. Tipps für den produktiven Einsatz  

Berechtigungen in Claude Code  

Claude Code fragt bei jedem MCP-Aufruf um Erlaubnis. Man kann häufig verwendete Aufrufe in den Permissions erlauben, damit man nicht jedes Mal bestätigen muss.  

Dazu fügt man die gewünschten MCP-Tool-Namen in der settings.local.json unter “permissions” > “allow” hinzu, z. B.:  

{ 
      "permissions": {  
            "allow": [  
                 "mcp__greyhound__RpcInfo_GetServerInfo",   
                 "mcp__greyhound__RpcItems_GetList",  
                 "mcp__greyhound__RpcItems_Get", 
                 "mcp__greyhound__RpcTextBlocks_GetCompleteList"  
             ]  
      },  
      "enableAllProjectMcpServers": true  
}  

Locking beachten  

GREYHOUND erfordert, dass Items vor Änderungen gesperrt (gelockt) werden. Der Workflow ist:  

1. Item locken (RpcItems_Lock)  
2. Änderung durchführen (z. B. SetUser, SetColor, SetTopic)  
3. Item unlocken (RpcItems_Unlock)  

Ohne Lock erhält man einen Error 905. Manche Operationen (z. B. AddRemark) geben den Lock automatisch frei, andere (z. B. SetUser) nicht.  

Zusammenfassung – Die 5 Schritte zum Erfolg mit Clauce Code 

1. DNS-Subdomain anlegen (A-Record auf GREYHOUND-Server-IP)  
2. SSL-Zertifikat im GCC aktivieren (Let’s Encrypt)  
3. API-Benutzer mit Bearer-Token in GREYHOUND erstellen  
4. .mcp.json mit URL und Token im Projektverzeichnis anlegen  
5. Claude Code starten und mit /mcp die Verbindung prüfen