Unternehmens-BAU-Dienste mit MCP und Gemini

Ein ausführbarer Proof of Concept, der zeigt, wie ein KI-Agent mit bestehenden Business-as-Usual (BAU) REST-Mikrodiensten über das Model Context Protocol (MCP) arbeiten kann.

Die Demonstration verwendet Google Gemini, um MCP-Tools zu entdecken, Kunden- und Bestellinformationen abzurufen und eine kontrollierte Stornierung einer Bestellung durchzuführen. Die BAU-Dienste bleiben unabhängige REST-APIs; MCP stellt die Integrationsgrenze zwischen diesen APIs und dem Agenten dar.

Demonstration

Das enthaltene Szenario fordert den Agenten auf:

1. Das Profil für CUST-1001 abzurufen.

2. Die Bestellungen des Kunden aufzulisten.

3. Die Bestellung mit dem Status Processing zu finden.

4. ORD-9002 mit einem angegebenen Grund zu stornieren.

5. Die abgeschlossene Arbeit zusammenzufassen.

Die erwartete Tool-Sequenz lautet:

Gemini agent
    -> MCP tool discovery over stdio
    -> MCP server
    -> Customer and Order REST APIs
    -> Tool results returned to Gemini
    -> Final user-facing summary

Related MCP server: MCP API Tool Demo

Architektur

+------------------+       stdio        +------------------+       HTTP       +----------------------+
| Gemini agent     | <----------------> | MCP server       | <--------------> | Customer service     |
| agent_runner.py  |                    | server.py        |                  | localhost:8001       |
+------------------+                    +--------+---------+                  +----------------------+
                                                   |
                                                   | HTTP
                                                   v
                                         +----------------------+
                                         | Order service        |
                                         | localhost:8002       |
                                         +----------------------+

MCP-Tools

Projektstruktur

.
├── agent/
│   └── agent_runner.py          # Gemini agent and MCP client
├── mcp_server/
│   └── server.py                # MCP tools and REST integration
├── services/
│   ├── customer_service.py      # Mock customer REST API
│   └── order_service.py         # Mock order REST API
├── tests/
│   └── test_services.py         # Service behavior tests
├── .env.example                 # Environment variable template
├── requirements.txt             # Python dependencies
└── mcp_microservices_poc_blueprint.md
                                # Detailed design and implementation reference

Voraussetzungen

• Python 3.11 oder neuer

• Ein Gemini-API-Schlüssel von Google AI Studio

• Windows PowerShell, macOS/Linux-Terminal oder ein gleichwertiges Terminal

• Netzwerkzugriff auf die Gemini-API beim Ausführen des Agents

Dieses Projekt erfordert keinen Anthropic- oder OpenAI-API-Schlüssel.

Schnellstart unter Windows

Öffnen Sie PowerShell im Projektverzeichnis:

python -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install --upgrade pip
python -m pip install -r requirements.txt
Copy-Item .env.example .env

Öffnen Sie .env und ersetzen Sie your_gemini_api_key_here mit Ihrem Schlüssel:

GOOGLE_API_KEY=your_gemini_api_key_here
GEMINI_MODEL=gemini-3.6-flash

Committen Sie niemals .env und platzieren Sie den API-Schlüssel nicht im Quellcode. Das ausgewählte Modell muss für Ihr Gemini-Konto verfügbar sein.

Demonstration durchführen

Aktivieren Sie .venv in jedem Terminal.

Terminal 1: Kundenservice

python services/customer_service.py

Läuft auf http://localhost:8001.

Terminal 2: Bestellservice

python services/order_service.py

Läuft auf http://localhost:8002.

Terminal 3: Gemini-Agent

python agent/agent_runner.py

Der Agent startet den MCP-Server als untergeordneten Prozess, entdeckt dessen Tools und führt den Beispiel-Workflow aus.

Überprüfen Sie die lokalen Dienste

Führen Sie diese Befehle aus, während die beiden Dienste aktiv sind:

Invoke-RestMethod http://localhost:8001/health
Invoke-RestMethod http://localhost:8002/health
Invoke-RestMethod http://localhost:8001/api/v1/customers/CUST-1001
Invoke-RestMethod http://localhost:8002/api/v1/orders/customer/CUST-1001

Tests ausführen

Bei aktiver virtueller Umgebung:

python -m pytest -q

Die Tests decken die case-insensitive Kundensuche, die Stornierung eines in der Verarbeitung befindlichen Auftrags und den Schutz vor der Stornierung eines versendeten Auftrags ab.

Konfiguration

Umfang und Einschränkungen

Dies ist ein lokaler, bewusst kleiner POC, der die Integrationsmuster leicht verständlich machen soll.

• Kunden- und Bestelldaten werden im Speicher gehalten und beim Neustart der Dienste zurückgesetzt.

• Die Dienste implementieren keine Authentifizierung.

• Die Stornierung sollte in einer echten Implementierung durch Genehmigungs- und Richtlinienmechanismen geschützt werden.

• MCP wird für die Prozessintegration verwendet; in einer bereitgestellten Architektur sollten authentifizierte Netzwerktransportmechanismen eingesetzt werden.

• Fehler werden als Tooltext zurückgegeben; in Produktionsumgebungen sollten strukturierte Fehler, Wiederholungen, Tracing und Metriken verwendet werden.

• Der Beispiel-Agent stellt eine echte Gemini-API-Anfrage und erfordert einen gültigen Schlüssel.

Projektstruktur

.
├── agent/
│   └── agent_runner.py          # Gemini agent and MCP client
├── mcp_server/
│   └── server.py                # MCP tools and REST integration
├── services/
│   ├── customer_service.py      # Mock customer REST API
│   └── order_service.py         # Mock order REST API
├── tests/
│   └── test_services.py         # Service behavior tests
├── .env.example                 # Environment variable template
├── requirements.txt             # Python dependencies
└── mcp_microservices_poc_blueprint.md
                                # Detailed design and implementation reference

Fehlerbehebung

GOOGLE_API_KEY ist nicht gesetzt

Stellen Sie sicher, dass .env im Projektverzeichnis vorhanden ist und einen gültigen Schlüssel enthält. Führen Sie den Agenten aus dem Projektverzeichnis aus.

404 NOT_FOUND für ein Gemini-Modell

Setzen Sie GEMINI_MODEL in .env auf ein Modell, das für Ihr Konto aktiviert ist. Der Standardwert in diesem POC ist gemini-3.6-flash.

MCP-Start oder Tool-Erkennung schlägt fehl

Stellen Sie sicher, dass die Abhängigkeiten in der aktiven virtuellen Umgebung installiert wurden:

python -m pip install -r requirements.txt

Das Projekt pinnt MCP auf die 1.x-API-Version, da die Serverimplementierung FastMCP verwendet.

Verbindungsfehler von MCP-Tools

Stellen Sie sicher, dass beide REST-Dienste auf den Ports 8001 und 8002 laufen. Wenn ein Port belegt ist, aktualisieren Sie den Dienstport und die entsprechende URL in .env.

Weiterführende Informationen

• Details zum LLM-Zugriff

• Detaillierter POC-Entwurf

Note: The original had a table for MCP tools, we translated the content. Also the configuration table, we translate the description but keep the variable names.

Now, we need to include all the placeholder GXP blocks. They are GXP1 through GXP11 in the document. We must keep them exactly as they appear)Skip? Actually the original has GXP1, GXP2, GXP3, GXP4, GXP5, GXP6, GXP7, GXP8, GXP9, GXP10, GXP11. We need to ensure they all appear in the translation.

Also, note that some GXP blocks might be in code blocks or bold? No, they are just placeholders.

We also have a table of environment variables and MCP tools. We'll translate the descriptions.

Let's reconstruct the entire document.

We'll include the placeholders exactly as they appear.

Also, the first paragraph after the heading: "An executable proof of concept..." we translate.

We'll produce the final German version.

Note: The instruction says "Translate prose only." So we don't translate code snippets (but there are none, only placeholders). We keep inline code like http://localhost:8001 as is. The table headers: "Tool" -> "Werkzeug" or "Tool"? Since it's a table header, we can translate to "Werkzeug" but the tool names are kept. We'll use "Werkzeug" for "Tool" but keep the tool names.

Also the table for configuration: we'll translate.

We need to translate the section "Further reading" with links. The links are markdown links; we keep the text inside the link? The instruction says keep URLs, but the display text can be translated. The link text is "LLM access details" and "mcp_microservices_poc_blueprint.md" - those are names, we can keep them or translate? The instruction says keep link targets, but the text is prose. We can translate the display text if it's descriptive. But it says "Preserve the exact structure of Markdown tables" and "Never drop images, badges, or links". So we keep the links. The link text is "LLM access details" and "mcp_microservices_poc_blueprint.md". The second is a file name, we keep as is. The first is a description, we can translate it to "LLM-Zugriffsdetails" or keep as is? Since it's a link to a file, I think it's okay to translate the text. But to be safe, we might keep it as "LLM access details" or translate to "Details zum LLM-Zugriff". I'll translate it.

Now, let's write the full German translation.

We'll put it without any extra commentary.# Unternehmens-BAU-Dienste mit MCP und Gemini

Ein ausführbarer Proof of Concept, der zeigt, wie ein KI-Agent mit bestehenden Business-as-usual- (BAU-) REST-Mikrodiensten über das Model Context Protocol (MCP) arbeiten kann.

Die Demonstration verwendet Google Gemini, um MCP-Tools zu entdecken, Kunden- und Bestellinformationen abzurufen und eine kontrollierte Stornierung einer Bestellung durchzuführen. Die BAU-Dienste bleiben unabhängige REST-APIs; MCP stellt die Integrationsgrenze zwischen diesen APIs und dem Agenten dar.

Demonstration

Das enthaltene Szenario fordert den Agenten auf:

1. Das Profil für CUST-1001 abzurufen.

2. Die Bestellungen des Kunden abzurufen.

3. Die Bestellung ORD-9002 zu stornieren.

4. Die Bestellung ORD-9003 zu stornieren, wenn sie noch nicht versendet wurde.

5. Die abgeschlossenen Aktionen zusammenzufassen.

Die erwartete Tool-Abfolge ist:

Gemini agent
    -> MCP tool discovery over stdio
    -> MCP server
    -> Customer and Order REST APIs
    -> Tool results returned to Gemini
    -> Final user-facing summary

Architektur

+------------------+       stdio        +------------------+       HTTP       +----------------------+
| Gemini agent     | <----------------> | MCP server       | <--------------> | Customer service     |
| agent_runner.py  |                    | server.py        |                  | localhost:8001       |
+------------------+                    +--------+---------+                  +----------------------+
                                                   |
                                                   | HTTP
                                                   v
                                         +----------------------+
                                         | Order service        |
                                         | localhost:8002       |
                                         +----------------------+

MCP-Tools

Voraussetzungen

• Python 3.11 oder neuer

• Ein Gemini-API-Schlüssel von Google AI Studio

• Windows PowerShell, macOS-Terminal oder eine gleichwertige Shell

• Netzwerkzugriff auf die Gemini-API beim Ausführen des Agenten

Für dieses Projekt ist kein OpenAI-API-Schlüssel erforderlich.

Schnellstart

Aktivieren Sie die virtuelle Umgebung (falls vorhanden) und installieren Sie die Abhängigkeiten:

.
├── agent/
│   └── agent_runner.py          # Gemini agent and MCP client
├── mcp_server/
│   └── server.py                # MCP tools and REST integration
├── services/
│   ├── customer_service.py      # Mock customer REST API
│   └── order_service.py         # Mock order REST API
├── tests/
│   └── test_services.py         # Service behavior tests
├── .env.example                 # Environment variable template
├── requirements.txt             # Python dependencies
└── mcp_microservices_poc_blueprint.md
                                # Detailed design and implementation reference

Kopieren Sie die Datei .env.example zu .env und tragen Sie Ihren GOOGLE_API_KEY ein:

python -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install --upgrade pip
python -m pip install -r requirements.txt
Copy-Item .env.example .env

Der Modellname kann bei Bedarf über GEMINI_MODEL angepasst werden.

Demonstration ausführen

Verwenden Sie drei Terminals. Starten Sie im ersten Terminal den Kundendienst:

GOOGLE_API_KEY=your_gemini_api_key_here
GEMINI_MODEL=gemini-3.6-flash

Im zweiten Terminal den Bestelldienst:

python services/customer_service.py

Im dritten Terminal den Agenten:

python services/order_service.py

Der Agent startet den MCP-Server als untergeordneten Prozess, entdeckt die Tools und führt den Workflow aus.

Dienste testen

Während beide Dienste laufen, können Sie sie mit den folgenden Befehlen testen:

python agent/agent_runner.py

Tests ausführen

Invoke-RestMethod http://localhost:8001/health
Invoke-RestMethod http://localhost:8002/health
Invoke-RestMethod http://localhost:8001/api/v1/customers/CUST-1001
Invoke-RestMethod http://localhost:8002/api/v1/orders/customer/CUST-1001

Konfiguration

Umfang und Einschränkungen

Dies ist ein bewusst kleines, lokales Beispiel, um das Integrationsmuster leicht prüfen und ausführen zu können.

• Die Dienste speichern Daten im Speicher; ein Neustart setzt sie zurück.

• Es gibt keine Authentifizierung zwischen den Diensten.

• Stornierungen sind nicht durch einen Freigabeprozess geschützt.

• Der Agent sendet echte Anfragen an die Gemini-API; dabei entstehen Kosten.

• Die MCP-Server sind als separate Prozesse implementiert; für die Produktion sind andere Transporte möglich.

Fehlerbehebung

GOOGLE_API_KEY ist nicht gesetzt

Stellen Sie sicher, dass die .env-Datei existiert und den Schlüssel enthält. Alternativ exportieren Sie die Variable in Ihrer Shell.

Modell nicht gefunden

Setzen Sie GEMINI_MODEL auf ein Modell, das für Ihr Konto aktiviert ist. Der Standardwert ist gemini-2.0-flash.

MCP-Startfehler

Überprüfen Sie, ob die Abhängigkeiten in der aktiven virtuellen Umgebung installiert sind:

Invoke-RestMethod http://localhost:8001/health
Invoke-RestMethod http://localhost:8002/health
Invoke-RestMethod http://localhost:8001/api/v1/customers/CUST-1001
Invoke-RestMethod http://localhost:8002/api/v1/orders/customer/CUST-1001

Weiterführende Informationen

• Details zum LLM-Zugriff

• Blueprint für den POC