MCP-Server selber bauen: Vom Prototyp zum produktiven Retrieval-Layer

Warum dieser Artikel existiert

Die Schritt-für-Schritt-Anleitung von Till bringt dich zum ersten funktionierenden MCP-Server. Niclas' Verlags-Artikel zeigt, warum ein MCP-Server für Content-Geschäftsmodelle strategisch ist.

Dieser Artikel füllt die Lücke dazwischen: Was muss passieren, damit aus dem Prototyp ein Layer wird, an den du dein Geschäft hängen kannst? Ich schreibe das aus der CTO-Rolle bei Till Freitag heraus – nach inzwischen sechs MCP-Server-Projekten, von denen drei in Production laufen.

Die fünf Schichten, die ein Prototyp nicht hat

Ein guter MCP-Prototyp ist 200 Zeilen TypeScript und ein paar Tool-Definitions. Ein produktionsreifer MCP-Server hat fünf zusätzliche Schichten – jede davon ist kein Beiwerk, sondern ein eigenes kleines System.

1. Auth- und Permission-Modell

Der häufigste Fehler in MVPs: Ein einziger API-Key, der alles kann. In Production brauchst du:

• OAuth 2.1 mit Dynamic Client Registration – damit jeder Claude-, Codex- oder Cursor-Workspace einen eigenen Token bekommt
• Scoped Tokens auf Tool-Ebene: nicht jeder Nutzer darf jedes Tool aufrufen
• Tenant-Isolation – bei Multi-Tenant-SaaS gehört der Tenant-Identifier in jeden Query, nicht in den App-Code
• Audit-Log pro Tool-Call: wer hat wann was abgefragt, mit welchem Token

Wir nutzen meistens Supabase oder Clerk als Auth-Provider und schreiben einen dünnen Middleware-Layer im MCP-Server, der den eingehenden Token validiert und in einen Permission-Kontext übersetzt.

2. Retrieval-Strategie

Hier verdient sich der Server seinen Namen. Ein Tool wie search_documents ist nur so gut wie das, was darunter liegt:

• Hybrid Search: BM25 plus Vektoren plus Filter. Reine Vektor-Suche ist selten gut genug.
• Re-Ranking: Cohere Rerank oder ein kleines lokales Modell, das die Top-50 auf Top-5 verdichtet.
• Chunking-Strategie, die zur Domäne passt. Verträge brauchen anderes Chunking als Produktdokumentation.
• Metadata-Filter als First-Class-Citizen – Datum, Quelle, Vertraulichkeit, Sprache.

Für die meisten Mid-Market-Projekte reicht ein Setup aus pgvector (oder Supabase Vector) plus Cohere Rerank plus eine eigene Chunking-Pipeline. Pinecone, Weaviate und Co. lohnen sich erst ab signifikanter Datenmenge.

3. Caching

Agenten sind verschwenderisch. Sie rufen dasselbe Tool oft mehrfach hintereinander auf, manchmal mit minimal anderen Argumenten. Ohne Cache merkst du das spätestens auf der LLM-Gateway-Rechnung.

• Request-Level-Cache für identische Tool-Calls (kurze TTL, z.B. 60 Sekunden)
• Embedding-Cache für häufig wiederkehrende Queries
• Negative Cache für leere Ergebnisse, damit teure Suchen nicht in Schleifen feuern

Wir nutzen Upstash Redis als Default – billig, schnell, edge-deployed.

4. Observability

Wenn ein Agent merkwürdige Antworten gibt, willst du sehen, welche Tool-Calls er gemacht hat, mit welchen Argumenten, wie lange die gedauert haben und was zurückkam. Ohne das debuggst du im Dunkeln.

• Strukturierte Logs pro Tool-Call mit Trace-ID
• Latency-Metriken pro Tool – Agenten geben auf, wenn Tools langsam sind
• Token-Counting auf Server-Seite, nicht nur auf Client-Seite
• Error-Tracking mit Sentry oder ähnlich, mit Sampling

5. Update-Pfad für Tool-Schemas

Das Schema eines Tools ist eine API – und APIs altern. Wenn du search_documents heute mit drei Parametern launchst und morgen einen vierten brauchst, hast du Clients in freier Wildbahn.

• Versioniere Tools explizit (search_documents_v2) statt Schema-Breaking-Changes
• Deprecation-Policy mit klarem Zeitfenster
• Capabilities-Discovery so bauen, dass Agenten den Wechsel selbst mitbekommen

Architektur, die wir aktuell empfehlen

Für die meisten Mid-Market-Kunden sieht der Stack so aus:

┌──────────────────────────────────────────────────────────┐
│  Claude / Codex / Cursor / Claude Cowork                 │
└─────────────────────────┬────────────────────────────────┘
                          │ MCP (HTTP/SSE)
                          ▼
┌──────────────────────────────────────────────────────────┐
│  MCP Server (TypeScript, Hono auf Cloudflare Workers)    │
│  ├─ OAuth Middleware (Supabase / Clerk)                  │
│  ├─ Tool Router                                          │
│  ├─ Request Cache (Upstash Redis)                        │
│  └─ Observability (Axiom / Logflare)                     │
└─────────────────────────┬────────────────────────────────┘
                          │
        ┌─────────────────┼─────────────────┐
        ▼                 ▼                 ▼
   Hybrid Search     Source APIs       Vector Store
   (pgvector +       (CRM, ERP,        (pgvector)
    BM25 + Rerank)    DMS)

Das ist nicht die schickste Architektur, aber die billigste, die produktionstauglich ist. Cloudflare Workers gibt uns Edge-Latenz unter 50ms in Europa, pgvector reicht für die meisten Datenmengen, Hono ist klein genug, dass das Setup an einem Tag steht.

Anti-Patterns, die wir mehrfach gesehen haben

• Ein riesiges query-Tool, das alles kann. Agenten kommen damit nicht klar. Lieber 5 klar geschnittene Tools mit eindeutigen Verben.
• Tool-Beschreibungen aus der internen Doku copy-pasten. Beschreibungen sind Prompts. Schreib sie aus Agenten-Sicht.
• Permissioning erst nachträglich. Es ist 10x billiger, das Permission-Modell vor dem ersten produktiven Call zu haben.
• Kein Rate-Limiting. Ein Agent in Endlosschleife kann dir an einem Wochenende ein Cloud-Budget zerschießen.

Was zwischen Prototyp und Production wirklich Zeit kostet

In unseren Projekten ist die Zeitverteilung ungefähr:

• 10% Tool-Definitionen und Server-Skelett
• 25% Auth, OAuth-Flows, Permission-Modell
• 30% Retrieval-Qualität (Chunking, Ranking, Evaluierung)
• 15% Caching, Rate-Limiting, Observability
• 20% Iteration mit echten Agenten, Anpassung der Tool-Schemas und Beschreibungen

Wenn jemand dir verspricht, das in einer Woche zu liefern, schaut euch das Retrieval-Setup genau an.

Wann lohnt sich Eigenbau, wann nicht

Eigenbau lohnt, wenn:

• Du proprietäre Daten hast, die ein Differentiator sind
• Bestehende Backends (REST, GraphQL, DB) gekapselt werden sollen
• Tenant-Isolation und Compliance-Anforderungen hoch sind

Eigenbau lohnt nicht, wenn:

• Es einen guten offiziellen MCP-Server gibt (monday, Notion, GitHub etc.) – dann ist der die Default-Wahl
• Der Use-Case rein lesend und öffentlich ist – dann ist ein Proxy auf eine fertige Such-API meist besser

Fazit

Ein MCP-Server ist heute keine technische Wette mehr – die Frage ist nur, wie ernst du ihn meinst. Wenn er ein Distributionskanal werden soll (siehe Tills Artikel), muss er produktionsreif sein. Die fünf Schichten oben sind unsere Pflicht-Checkliste.

Wenn du gerade an einem MCP-Server arbeitest oder einen brauchst, der mehr aushält als die nächsten zwei Demos: Lass uns kurz sprechen →