CGS IT Solutions GmbH — Claude Code Training · Modul 8 · MCP im Detail · v0.11.5

Modul 8

MCP im Detail

Vertiefung · Model Context Protocol

Inhalt

1Konzepte & Vokabular — was MCP ist, Client/Server/Tools, Transport 2Server verwenden — .mcp.json, Scopes, Freigabe, echtes Beispiel 3Temporäre Server — phasen-gebunden, nur in Debug-/Test-Phasen (Quarkus Dev MCP) 4Eigenen Server bauen — einen Service als MCP-Server exponieren (Quarkus) 5CLI, Skill oder MCP? — Entscheidung nach Lücke, was MCP mehr kann, Token Overhead, Lock-in Übung — einen eigenen Tool-Endpoint exponieren Glossar — Begriffe zum Nachschlagen

Konzepte & Vokabular

Was MCP ist

MCP (Model Context Protocol) ist ein offenes Protokoll, über das ein Client wie Claude Code strukturiert an fremde Werkzeuge und Daten andockt — einmal gebaut, an jedem Client nutzbar.

  1. Client und Server sprechen dieselbe Sprache — unabhängig davon, wer sie gebaut hat.
  2. Nicht proprietär: ein Server, den ihr einmal schreibt, funktioniert an jedem MCP-fähigen Client, nicht nur an Claude Code.
  3. Strukturiert statt Text: der Agent bekommt aufrufbare Funktionen mit Parametern, kein Freitext zum Parsen.
Clients
Claude Code
andere IDE
anderer Client
MCPein Protokoll
euer Servereinmal gebaut
Ticketsystem
Datenbank · API
spricht MCPwas dahinter liegt
MCP ist der Anti-Lock-in-Teil des Stacks: ein Protokoll, kein Produkt.

Das Vokabular Glossar

Sechs Begriffe genügen, um jede MCP-Config zu lesen — in der Praxis begegnen euch fast nur die ersten drei.

Client

Die Anwendung, in der das Modell läuft — hier Claude Code. Verbindet sich zu Servern.

Server

Ein Prozess, der Fähigkeiten anbietet. Lokal gestartet oder remote erreichbar.

Tools

Aufrufbare Funktionen mit Parametern — das, was der Agent tatsächlich ausführt.

Resources

Lesbare Inhalte, die der Server bereitstellt — Dokumente, Datensätze, Zustände.

Prompts

Vom Server mitgelieferte Vorlagen, die der Nutzer auswählen kann.

Connectors

Fertige, gehostete Anbindungen an Dienste — MCP als Produkt statt Selbstbau.

checked am 2026-07-24 gegen code.claude.com

Die Sprache: selbstbeschreibende Tools

Die „Sprache" ist JSON-RPC — und der Server liefert die API gleich mit: jedes Tool beschreibt sich selbst über Name, Beschreibung und ein JSON-Schema der Parameter.

  1. Kein separates API-Dokument: die description ist das, was das Modell liest, um zu entscheiden, wann es das Tool nutzt.
  2. inputSchema ist JSON-Schema: Typen, Pflichtfelder, Beschreibungen — daraus baut der Client den Aufruf.
  3. Selbstbeschreibend: der Server sagt dem Client, was er kann — der Client muss nichts fest verdrahten.
// Der Server deklariert jedes Tool selbst
{
  "name": "freeSeats",
  "description": "Freie Plätze eines Seminars abfragen",
  "inputSchema": {
    "type": "object",
    "properties": {
      "seminarId": { "type": "integer",
        "description": "Seminar-ID" }
    },
    "required": ["seminarId"]
  }
}
Genau diese Definition erzeugt später eure @Tool-Annotation automatisch — ihr schreibt die Methode, MCP macht daraus die Beschreibung.
checked am 2026-07-24 gegen modelcontextprotocol.io

Wie der Client die Tools kennt: Discovery

Der Client kennt die Tools nicht vorab — er fragt sie beim Verbinden ab (tools/list) und legt Beschreibung und Schema dem Modell vor.

1
Client
verbinden: welche Fähigkeiten?
2
tools/list
alle Tool-Definitionen
3
Modell
sieht Name, Beschreibung, Schema
4
tools/call
Ergebnis
wer handeltwas fließt
// 1. Client entdeckt die Tools
--> "method": "tools/list"
<-- "tools": [ { "freeSeats", … } ]

// 2. Modell wählt, Client ruft auf
--> "method": "tools/call",
    "params": { "name": "freeSeats",
      "arguments": { "seminarId": 7 } }
<-- "result": { "content": [ … ] }
/mcp zeigt euch genau das Ergebnis von tools/list — die Tools, die der Server zur Laufzeit angemeldet hat.
checked am 2026-07-24 gegen modelcontextprotocol.io

Transport: lokaler Prozess oder Remote-Dienst

Ein MCP-Server läuft entweder als lokaler Prozess (stdio) oder als Remote-Dienst (HTTP) — die Config verrät sofort, welcher.

  1. stdio (lokal): command + args starten einen Child-Process; Claude Code redet über stdin/stdout — kein Netzwerk.
  2. HTTP (remote): type: "http" + url — Verbindung zu einem laufenden Dienst über das Netz.
  3. Faustregel: steht command drin, ist es lokal; steht url drin, ist es remote.
// stdio — lokaler Prozess
"angular": {
  "command": "npx",
  "args": ["-p", "@angular/cli", "ng", "mcp"]
}

// http — Remote-Dienst
"stripe": {
  "type": "http",
  "url": "https://mcp.stripe.com"
}
Der Unterschied ist sicherheitsrelevant: ein Remote-Server sieht, was ihr ihm schickt; ein stdio-Server läuft in eurer eigenen Umgebung.
checked am 2026-07-24 gegen code.claude.com

Server verwenden

.mcp.json: Scopes & Freigabe

Wo ein Server konfiguriert ist, entscheidet, wer ihn bekommt — und jeder Server wird beim ersten Start einzeln freigegeben.

  1. Project — .mcp.json im Repo-Root, per Versionskontrolle geteilt: das ganze Team bekommt dieselben Server.
  2. Local — nur für dich in diesem Projekt (in ~/.claude.json), z. B. für Server mit persönlichen Credentials.
  3. User — für dich über alle Projekte hinweg.
  4. Freigabe: ein Server aus dem Repo ist erst mal fremder Code — er läuft erst nach expliziter Zustimmung.
# Scope-Ablage
Project .mcp.json (Repo-Root, geteilt)
Local ~/.claude.json (privat)
User ~/.claude.json (alle Projekte)

# Status prüfen
/mcp # zeigt Server + Tools + Freigabe
/mcp zeigt jederzeit, welche Server verbunden sind und welche Werkzeuge sie anbieten.
checked am 2026-07-24 gegen code.claude.com

Echtes Beispiel: der Angular-Server

Aus cgsit-finance — genau ein Server, ein lokaler stdio-Prozess, und der aus gutem Grund.

  1. Was er kann: u. a. get_best_practices, list_projects, search_documentation, run_target — Wissen nach dem Trainings-Cutoff, das keine CLI so ausliefert. Doku: angular.dev/ai/mcp.
  2. Lokal, kein Netz: command: npx startet ng mcp als Child-Process; Internet berührt nur der einmalige Paket-Download.
  3. Die Disziplin: ein Server, nicht fünf — jeder legt seine Tool-Beschreibungen in jeden Kontext.
// .mcp.json — Repo-Wurzelverzeichnis
{
  "mcpServers": {
    "angular": {
      "command": "npx",
      "args": ["-p", "@angular/cli", "ng", "mcp"],
      "cwd": "…/cgsit-finance-web"
    }
  }
}
Tipp: Jeder Server muss sich gegen eine Frage rechtfertigen: Was kann er, das ein vorhandenes CLI nicht kann?
checked am 2026-07-24 gegen cgsit-finance + angular.dev

Tool-Namen & wie der Agent sie ruft

Jedes Tool eines Servers trägt einen eindeutigen Namen nach festem Schema — so weiß der Agent, welchen Server er anspricht.

  1. Namensschema: mcp__<server>__<tool> — der Präfix macht sichtbar, woher ein Werkzeug kommt.
  2. Freigabe pro Tool: in settings.local.json stehen die erlaubten Tools namentlich — nicht der ganze Server pauschal.
  3. Kosten im Blick: jeder aktive Server lädt seine Tool-Definitionen in jede Runde (Modul 1: alles wird neu geschickt).
// .claude/settings.local.json
"enabledMcpjsonServers": [ "angular" ],
"permissions": {
  "allow": [
    "mcp__angular__list_projects",
    "mcp__angular__get_best_practices"
  ]
}
checked am 2026-07-24 gegen cgsit-finance

Temporäre & phasen-gebundene Server

Permanent oder nur in der Phase?

Nicht jeder Server soll dauerhaft verbunden sein — manche hängen an einer Ressource, die nur zeitweise läuft (z. B. eine lokale Dev-Instanz zum Debuggen).

Permanent

  • Doku-/Best-Practice-Server (z. B. Angular)
  • braucht keine laufende lokale Ressource
  • eingecheckt im Projekt-Scope, dauerhaft verbunden

Temporär

  • Introspektion einer laufenden Dev-Instanz (Quarkus Dev MCP)
  • braucht die laufende Ressource — sonst existiert der Endpoint nicht
  • Skript-getriggert im lokalen Scope, nur in der Phase
Entscheidungsregel: Hängt der Server an einer Ressource, die nur zeitweise läuft — temporär. Prozess einchecken, Zustand lokal halten.
checked am 2026-07-24 gegen cgsit-finance

Warum nicht dauerhaft anlassen

Ein eingecheckter Endpoint, der nur zeitweise erreichbar ist, kostet mehr, als er nützt — auf drei Arten.

  1. Kontext-/Token-Kosten: die Tool-Definitionen eines verbundenen Servers fließen in jede Anfrage ein (Tool-Suche) — auch wenn er gerade nichts tut.
  2. Toter Endpoint kostet Zeit: konfiguriert, aber nicht erreichbar — der Client wartet bei einem Tool-Call bis ~30 s auf Reconnect, bevor er „failed" meldet.
  3. Team-Rauschen: ein eingecheckter Endpoint, den nur eine Person lokal laufen hat, ist für alle anderen tot.
Deshalb: einen phasen-gebundenen Server nicht in die eingecheckte .mcp.json schreiben.
checked am 2026-07-24 gegen cgsit-finance

Prozess einchecken, nicht den An/Aus-Zustand

„Bin ich gerade in einer Debug-Phase?" ist eine lokale, flüchtige Tatsache pro Entwickler — geteilt und versioniert wird das Werkzeug, nicht der Zustand.

  1. Eingecheckt (teamweit): der Aktivierungs-Prozess (dev-mcp.sh) und die kanonische Server-Definition (URL, Transport).
  2. Nicht eingecheckt — wohin genau: --scope local schreibt nach ~/.claude.json im Home-Verzeichnis, an den Projektpfad gebunden — nicht in die eingecheckte .mcp.json.
  3. Kein toter Endpoint: weil der Zustand nur im Home liegt, hat kein anderer im Team einen konfigurierten, aber unerreichbaren Server.
# eingechecktes Skript kapselt Start + Registrierung
dev-mcp.sh up
  # Dev-Instanz starten, dann MCP LOKAL registrieren:
  claude mcp add --transport http seminar-dev \
    http://localhost:8080/mcp --scope local
  # schreibt nach ~/.claude.json (Home), an den
  # Projektpfad gebunden — NICHT in .mcp.json

dev-mcp.sh down
  # MCP LOKAL deregistrieren, dann Instanz stoppen:
  claude mcp remove seminar-dev
Bewusst kein enable/disable — der Zustand ergibt sich aus add und remove.
checked am 2026-07-24 gegen cgsit-finance + claude CLI

Eigenen Server bauen

Zusatzthema — über das Kern-Curriculum hinaus

Wann ein eigener MCP-Server lohnt

Ein eigener MCP-Server lohnt sich erst, wenn ein vorhandenes CLI oder Skill die Aufgabe nicht sauber löst.

Eigener Server lohnt sich

  • strukturierter Zugriff auf einen eigenen Dienst (DB, interne API), den kein Standard-CLI kennt
  • der Agent soll wiederholt und in jeder Session darauf zugreifen
  • die Antwort ist strukturiert und lässt sich schlecht aus Text parsen

Lieber CLI oder Skill

  • ein Shell-Kommando tut es einmalig genauso — kein Server-Betrieb nötig
  • es geht um ein Verfahren, nicht um Datenzugriff (dann Skill)
  • der Nutzen rechtfertigt die dauerhafte Kontext-Miete nicht (Block 4)

Anatomie: ein Server ist eine Menge Tools

Einen MCP-Server bauen heißt: Methoden als Tools deklarieren — Name, Beschreibung, typisierte Parameter, Rückgabewert.

  1. Ein Tool = eine Methode mit einer klaren Beschreibung, die dem Modell sagt, wann es sie nutzt.
  2. Parameter sind typisiert und beschrieben — daraus baut der Client das Aufruf-Schema.
  3. Transport ist Konfiguration, nicht Code: dieselbe Klasse läuft als stdio- oder als HTTP-Server.
ein Server
freeSeats(seminarId)
bookSeat(seminarId, user)
cancelBooking(id)
der Client sieht
Name · Beschreibung
Parameter-Schema
ein Tool = eine Methode

Code: ein eigener Server in Quarkus

Mit der Quarkus-MCP-Extension wird aus einer annotierten Methode ein Tool — die Fachlogik bleibt euer bestehender Service.

// pom.xml — stdio-Transport
io.quarkiverse.mcp:quarkus-mcp-server-stdio:1.6.1

// SeminarTools.java
public class SeminarTools {
  @Inject @RestClient SeminarApiClient api;

  @Tool(description = "Freie Plätze eines Seminars")
  FreeSeats free_seats(
    @ToolArg(description = "Mandant") String mandant,
    @ToolArg(description = "Seminar-ID") long id) { ... }

  record FreeSeats(long id, boolean exists, int freeSeats) {}
}
@Tool macht die Methode aufrufbar, @ToolArg beschreibt die Parameter — das JSON-Schema für den Client entsteht daraus beim Bauen.
checked am 2026-07-26 gegen docs.quarkiverse.io

Registrieren & testen

Der fertige stdio-Server wird wie jeder andere in .mcp.json eingetragen — als command, der euren Prozess startet.

  1. Bauen: das Quarkus-App-Artefakt erzeugen (mvn package).
  2. Erst ohne Client testen: probe.sh spricht dasselbe JSON-RPC — läuft es dort nicht, liegt es nie am Client.
  3. Registrieren: claude mcp add mit --scope local, oder als Team-Server in .mcp.json.
  4. Prüfen: /mcp zeigt den Server und seine Tools.
# nur für mich, nicht im Repository
claude mcp add seminar --scope local \
  -- java -jar target/quarkus-app/quarkus-run.jar

// oder fürs Team: .mcp.json
"seminar": { "command": "java",
  "args": ["-jar", "…/quarkus-run.jar"] }

/mcp # seminar: 5 tools [ok]
Ab jetzt kann der Agent mcp__seminar__free_seats aufrufen — strukturiert, ohne euren Service als Text zu parsen.
checked am 2026-07-26 gegen code.claude.com

CLI, Skill oder MCP?

Was ihr um ein externes Tool herum baut

Der Ausgangspunkt ist immer: ein externes Tool wird gebraucht.
Zwei Achsen entscheiden, ob und was ihr drumherum baut.

  1. Achse 1 — Erreichbarkeit: nur remote (z. B. eine REST-API) oder auch lokal als CLI (z. B. git)? Ein CLI bedient der Agent oft direkt.
  2. Achse 2 — Modell-Wissen: kennt das Modell das Tool/die API schon gut? Dann fehlt kein Grundwissen.
  3. Kennt es + erreichbar — oft reicht der direkte Aufruf, ganz ohne Ebene.
  4. Ein Skill kommt dazu, um die Verwendung zu konfigurieren, limitieren, tunen — oder um ein unbekanntes Tool zu beschreiben („rufe so auf").
erreichbar
Modell kennt es
Modell kennt es nicht
lokal als CLI
direkt aufrufenSkill nur fürs Ritual
Skill beschreibt„rufe so auf"
nur remote
Skill tuntModell macht den Aufruf
MCPnächste Folie
keine Ebene nötigSkill reichtProtokoll nötig
Ein Skill ist Text: er beschreibt und tunt die Verwendung — setzt aber voraus, dass am Ende das Modell den Aufruf selbst macht.
checked am 2026-07-24 gegen cgsit-finance

Was MCP kann, das ein Skill nicht kann

Ein MCP-Server abstrahiert den technischen Aufruf zu einem selbstbeschreibenden JSON-Tool — und sitzt dabei im Aufrufpfad.

  1. Abstraktion statt Beschreibung: der Server verpackt den rohen Call (z. B. ein SQL execute) in ein sauberes Tool — statt ihn zu erklären.
  2. Runtime Discovery, ohne Vortraining: Claude Code liest die Tools beim Verbinden dynamisch ein (JSON-Schema) — kein Vorwissen nötig.
  3. Zustand & Reichweite: der Server hält Zustand und erreicht interne Netze, die dem Terminal nicht offenstehen (z. B. hinter einer Firewall).
  4. Interceptor-Ebene: als Code im Aufrufpfad erzwingt der Server Zugriffskontrolle, Logging, Security, Billing — bei jedem Aufruf.
# Skill: nur Text/Anleitung
"führe das SQL so aus …"
# das Modell muss es können und selbst tun

# MCP-Server: Code im Aufrufpfad
Tool freeSeats(seminarId) -> JSON
  + Zugriffskontrolle + Logging
  + Security + Billing
Ein Skill ist Text, ein MCP-Server ist Code im Aufrufpfad — nur er kann Zugriffskontrolle, Audit und Billing erzwingen.
checked am 2026-07-24 gegen modelcontextprotocol.io

MCP vs. CLI: Token Overhead

Diese Abstraktion hat einen Preis: jeder aktive MCP-Server lädt seine Tool-Definitionen in den Kontext — in jeder Runde, auch ungenutzt.

MCP-Server

  • dauerhafte Kontext-Miete für alle Tools, auch die nie benutzten
  • lohnt, wenn Abstraktion, Vortraining-Freiheit oder Interceptor den Preis wert sind

CLI

  • nur im Kontext, wenn sie aufgerufen wird
  • passt, wenn der Agent das Tool ohnehin kann und erreicht
Context Hygiene: ein Server kostet in jeder Runde — git läuft dauernd über die CLI und braucht trotzdem kein MCP.
checked am 2026-07-24 gegen code.claude.com

Open Source & Vendor Lock-in

Weil MCP ein offenes Protokoll ist, bindet euch ein selbst gebauter Server an keinen Anbieter — er läuft an jedem MCP-fähigen Client.

  1. Ein Server, viele Clients: dieselbe Anbindung funktioniert über Werkzeuggrenzen hinweg.
  2. Eigener Code, eure Kontrolle: ein stdio-Server läuft in eurer Umgebung, nicht bei einem Dritten.
  3. Abwägung Connectors: gehostete Fertig-Anbindungen sind bequem, aber genau der Lock-in, den das Protokoll vermeidet.
Ein Server
  läuft an Claude Code,
  läuft an anderen MCP-Clients,
  läuft morgen an dem,
  den es noch nicht gibt.
Das ist der strategische Wert von MCP: Investition in eine Anbindung, nicht in einen Anbieter.

Gut zu wissen: RAG Glossar

Für Code braucht Claude Code kein Vektor-RAG: es sucht agentisch (Grep, Glob, Read) — treffsicherer und aktueller als ein Index, der veralten kann.

  1. Wann RAG doch passt: riesige externe Firmen-Dokus außerhalb des Repos (Confluence, Notion, PDF-Sammlungen) — angebunden als MCP-Server, der das Retrieval übernimmt.
  2. Dann ganz normal MCP: der Server macht das Retrieval, Claude Code ruft es als Tool auf — dieselbe Mechanik wie jeder andere Server (Achse: extern + Modell kennt eure Docs nicht).
  3. Abgrenzung: RAG ist meist das, was ihr für eure Kunden in eure Anwendungen baut — und Claude Code hilft beim Schreiben dieses Codes.
BeispielCheck our company wiki (via MCP-RAG) for the OAuth security compliance we must follow, and apply it to my code.
Nicht euren lokalen Code in eine Vektor-DB kippen — dafür ist die agentische Suche da (präziser, aktuell, keine Index-Pflege).

Übung — einen eigenen Tool-Endpoint exponieren

Aufgabe

1. seminar-api starten, examples/seminar-mcp bauen und mit claude mcp add --scope local registrieren.
2. Claude Code fragen: „Hält die Mandanten-Trennung von seminar-api?" — ohne ein Tool zu nennen. Die description muss die Wahl treffen.
3. Ein eigenes Tool ergänzen (z. B. kunde_lookup(mandant, email)) und den offenen Befund aus input_validation_audit erklären.

Verifizierbares Ergebnis: /mcp listet den Server samt eurem neuen Tool, und im Verlauf steht ein echter Aufruf von mcp__seminar__tenant_isolation_audit — nicht eine Vermutung über den Code.

Dauer ca. 30–40 Minuten · Zusatzthema, optional

Glossar Glossar

MCP (Model Context Protocol) Offenes Protokoll, über das ein Client wie Claude Code strukturiert an externe Werkzeuge und Datenquellen andockt.
Tool (MCP) Aufrufbare Funktion mit benannten Parametern, die ein MCP-Server anbietet und der Agent ausführt.
stdio (MCP-Transport) Betrieb eines MCP-Servers als lokaler Child-Process; Kommunikation über stdin/stdout statt Netzwerk.
Scope (MCP) Ablageort einer Server-Config, der bestimmt, wer sie bekommt: Project (geteilt via .mcp.json), Local und User (privat).

© 2026 CGS IT Solutions GmbH

Alle Rechte vorbehalten

Diese Schulungsunterlagen sind urheberrechtlich geschützt. Vervielfältigung, Weitergabe oder kommerzielle Nutzung — auch in Auszügen — nur mit ausdrücklicher schriftlicher Genehmigung der CGS IT Solutions GmbH.

cgsit-claude-training · Modul 8 · MCP · v0.11.5