Einen benutzerdefinierten MCP-Server erstellen, absichern und deployen: Von der Tool-Definition bis zur Produktion

Die meisten MCP-Tutorials hoeren bei “hier ist ein Tool, das Hello World zurueckgibt” auf. Das ist gut fuer das Erlernen des Protokolls, aber nutzlos, wenn Sie AI-Agenten mit einer echten Datenbank verbinden, Authentifizierung erzwingen, SQL-Injection verhindern und das Ganze fuer das Deployment verpacken muessen. Dieses Tutorial schliesst diese Luecke.

Sie werden einen MCP-Server bauen, der sich mit PostgreSQL verbindet, schema-validierte Query-Tools exponiert, API-Key-Authentifizierung durchsetzt, SQL-Injection-Praevention und sensible Spaltenmaskierung implementiert und in einem Docker-Container deployt. Der vollstaendige Code ist auf GitHub verfuegbar unter mcp-enterprise-starter. Fuer den strategischen Kontext, wann und warum Sie benutzerdefinierte MCP-Server erstellen sollten, siehe den Begleit-Blogpost: Building Custom MCP Servers for Enterprise AI Integration.

Bevor Sie beginnen, klonen Sie das Repo und installieren Sie die Abhaengigkeiten:

git clone https://github.com/InkByteStudio/mcp-enterprise-starter.git
cd mcp-enterprise-starter
npm install

Schritt 1: Den MCP-Server aufsetzen

Der Server verwendet das offizielle @modelcontextprotocol/sdk und exponiert Tools und Ressourcen ueber den stdio-Transport (fuer lokale IDE-Integration) oder den streamable-HTTP-Transport (fuer netzwerkbasiertes Deployment).

Die Projektstruktur ist standardmaessig modular organisiert: src/tools/ fuer Tool-Handler, src/resources/ fuer Ressourcen-Handler, src/middleware/ fuer Auth und Validierung, src/db/ fuer die Datenbankverbindung und src/config/ fuer die Konfiguration.

Das vollstaendige Tutorial im Repository fuehrt durch jeden Schritt mit vollstaendigen Codebeispielen. Hier sind die Schluesselkonzepte:

Server-Initialisierung

Die Server-Initialisierung registriert Tools und Ressourcen mit dem MCP SDK und konfiguriert den Transport. Der Server deklariert seine Faehigkeiten bei der Initialisierung, damit Clients (wie Claude Desktop oder VS Code) wissen, welche Tools verfuegbar sind, bevor sie Anfragen senden.

Transport-Konfiguration

Fuer lokale Entwicklung verwenden Sie stdio. Fuer Produktions-Deployments verwenden Sie den streamable-HTTP-Transport mit einer konfigurierbaren URL und Port. Die Transport-Wahl beeinflusst, wie der Server gestartet und verbunden wird, aendert aber nicht die Tool- und Ressourcen-Logik.

Schritt 2: Ihr erstes Tool definieren — sichere Datenbankabfrage

Das query_database-Tool akzeptiert eine SQL-Abfrage als Eingabe, validiert sie, fuehrt sie gegen PostgreSQL aus und gibt die Ergebnisse zurueck. Das Zod-Schema definiert die Eingabe, und die Sicherheits-Middleware stellt sicher, dass nur SELECT-Abfragen ausgefuehrt werden.

Schluesseldesign-Entscheidungen:

• Nur SELECT erlauben: Die Middleware lehnt INSERT, UPDATE, DELETE, DROP und andere mutierende Anweisungen ab
• Row-Limits erzwingen: Standardmaessig werden maximal 100 Zeilen zurueckgegeben, um Token-Verbrauch zu kontrollieren
• Parametrisierte Abfragen verwenden: Wo moeglich, um SQL-Injection zu verhindern
• Sensible Spalten maskieren: E-Mail-Adressen, Telefonnummern und andere PII werden in der Antwort maskiert

Schritt 3: Eine Ressource hinzufuegen — Schema-Erkennung

MCP-Ressourcen exponieren Daten fuer den Kontext, die Agenten verwenden koennen, um bessere Abfragen zu formulieren. Die database://schema-Ressource gibt die Datenbank-Tabellenstruktur zurueck, damit der Agent weiss, welche Tabellen und Spalten existieren, bevor er eine Abfrage formuliert.

Das ist entscheidend fuer nuetzliche Datenbankabfragen: Ohne Schema-Kontext muss der Agent Tabellennamen und Spaltentypen erraten, was zu fehlgeschlagenen Abfragen und verschwendeten Tokens fuehrt.

Schritt 4: Authentifizierung hinzufuegen

API-Key-Authentifizierung wird als Middleware implementiert, die jeden eingehenden MCP-Aufruf gegen eine konfigurierte Key-Liste prueft. Im stdio-Modus wird die Authentifizierung optional uebersprungen (da der Transport bereits lokal und vertrauenswuerdig ist). Im HTTP-Modus ist sie erzwungen.

Keys werden als SHA-256-Hashes in der Konfiguration gespeichert, nie als Klartext. Die Middleware gibt spezifische Fehler zurueck fuer fehlende Keys, ungueltige Formate und abgelaufene Keys.

Schritt 5: Eingabevalidierung und Sicherheits-Guardrails

Die Sicherheitsschicht umfasst:

• Schema-Validierung: Jede Tool-Eingabe wird gegen ein Zod-Schema validiert, bevor die Verarbeitung beginnt
• SQL-Injection-Praevention: Ein Parser prueft die Abfrage auf bekannte Injektionsmuster und lehnt sie ab
• Row-Limits: Maximale Ergebnisgroesse ist konfigurierbar und standardmaessig auf 100 begrenzt
• Sensible Spaltenmaskierung: Spalten, die als sensibel konfiguriert sind (E-Mail, Telefon, SSN), werden in der Ausgabe maskiert
• Timeout-Kontrolle: Abfragen, die laenger als der konfigurierte Timeout laufen, werden abgebrochen

Schritt 6: Fehlerbehandlung und strukturierte Antworten

MCP-Tools sollten Fehler zurueckgeben, ueber die Agenten nachdenken koennen. Statt generischer Fehlermeldungen definiert der Server Fehlerkategorien:

• VALIDATION_ERROR: Eingabe entspricht nicht dem Schema
• AUTH_ERROR: Authentifizierung fehlgeschlagen
• QUERY_ERROR: SQL-Fehler bei der Ausfuehrung
• TIMEOUT_ERROR: Abfrage hat das Zeitlimit ueberschritten
• PERMISSION_ERROR: Aktion nicht erlaubt

Jeder Fehler enthaelt einen maschinenlesbaren Code und eine menschenlesbare Nachricht, damit der Agent entweder wiederholen oder dem Benutzer erklaeren kann, was schief gelaufen ist.

Schritt 7: Tests

Das Projekt enthaelt Unit-Tests und Integrationstests:

• Unit-Tests fuer Tool-Handler testen, dass gueltige Abfragen Ergebnisse zurueckgeben und ungueltige Abfragen abgelehnt werden
• Unit-Tests fuer Middleware testen Auth-Durchsetzung und Validierungslogik
• Integrationstests verwenden eine Test-Datenbank, um den vollstaendigen Pfad vom MCP-Aufruf bis zur Datenbankantwort zu validieren

Fuehren Sie die Tests aus:

npm test

Schritt 8: Containerisieren und deployen

Das Projekt enthaelt ein Multi-Stage-Dockerfile und eine Docker-Compose-Konfiguration, die den MCP-Server zusammen mit PostgreSQL startet.

Das Dockerfile kompiliert TypeScript in der Build-Stage und fuehrt das Ergebnis als Non-Root-Benutzer in der Production-Stage aus. Die Docker-Compose-Konfiguration exponiert den HTTP-Endpunkt und verbindet den Server mit der Datenbank.

docker compose up --build

Nach dem Start koennen Sie den Server in Claude Desktop oder VS Code mit MCP-Unterstuetzung verbinden, indem Sie den HTTP-Endpunkt konfigurieren.

Verifizieren

Testen Sie den Health-Endpunkt:

curl http://localhost:3001/health

Verbinden Sie dann Claude Desktop oder Ihren bevorzugten MCP-Client mit dem Server und testen Sie eine Datenbankabfrage.

Haeufige Einrichtungsprobleme

Server startet, aber Tools erscheinen nicht im Client

Ursache: Der Client hat die Faehigkeiten nicht korrekt ausgehandelt, oder der Transport ist falsch konfiguriert.

Loesung: Pruefen Sie die Server-Logs auf Initialisierungsfehler. Stellen Sie sicher, dass der richtige Transport-Typ (stdio vs. HTTP) konfiguriert ist.

Datenbankverbindung schlaegt fehl

Ursache: PostgreSQL laeuft nicht oder die Verbindungsparameter sind falsch.

Loesung: Pruefen Sie, ob PostgreSQL erreichbar ist und die Konfiguration in .env korrekt ist. Bei Docker Compose stellen Sie sicher, dass der Service-Name als Hostname verwendet wird.

Abfragen werden als SQL-Injection abgelehnt

Ursache: Die Sicherheits-Middleware ist konservativ und kann legitime Abfragen mit bestimmten Mustern ablehnen.

Loesung: Ueberpruefen Sie die Regex-Muster in der SQL-Validierung und passen Sie sie fuer Ihren Anwendungsfall an.

Zusammenfassung

Sie haben nun einen produktionsnahen MCP-Server, der ueber Hello-World-Beispiele hinausgeht: sichere Datenbankabfragen mit Eingabevalidierung und SQL-Injection-Praevention, Schema-Erkennung als MCP-Ressource, API-Key-Authentifizierung, sensible Spaltenmaskierung, strukturierte Fehlerbehandlung, Tests und Docker-Deployment.

Die naechsten Schritte sind normalerweise: zusaetzliche Tools fuer Schreiboperationen (mit Genehmigungs-Workflows), Integration mit Ihrem bestehenden Identitaets-Stack statt einfacher API-Keys, Monitoring und Metriken, und die Anbindung an mehrere Datenquellen.

Fuer den strategischen Kontext, wann benutzerdefinierte MCP-Server Sinn machen und wie sie in eine breitere AI-Plattformstrategie passen, siehe Building Custom MCP Servers for Enterprise AI Integration. Fuer das Konfigurieren von MCP-Tools fuer Coding-Agenten, siehe GitHub Copilot Coding Agent mit MCP-Tools erweitern.