Invoice Processor als MCP-Tool bereitstellen

Connic kann die vorhandene Vorlage Invoice Processor als MCP-Tool bereitstellen. Ein Client übergibt Rechnungstext, der Agent extrahiert die Felder und prüft die Berechnungen mit Python-Tools. Die Verbindung gibt das Ergebnis zurück. Dafür genügen die Agentendateien der Vorlage und eine verwaltete MCP-Server-Verbindung.

Die Agenten der Vorlage

Die Vorlage Invoice Processor aus Connic Awesome Agents enthält drei Agenten. invoice-extractor liest Rechnungstext und gibt Felder wie Lieferant, Währung, Rechnungspositionen und Gesamtbetrag zurück. Dafür nutzt er Python-Rechentools und ein Ausgabeschema für Rechnungen. invoice-validator prüft die extrahierten Beträge deterministisch. invoice-pipeline führt beide nacheinander aus und gibt die abschließende Zusammenfassung des Validators zurück.

Diese Anleitung stellt invoice-extractor bereit, damit der Aufrufer die extrahierten Rechnungsfelder erhält. Connic hostet den MCP-Endpoint und leitet den Tool-Aufruf an den bereitgestellten Agenten weiter. Der Python-Code unten dient als Client, der diesen Endpoint untersucht und aufruft. Der Artikel zu MCP-Servern und -Clients erklärt die Rollen im Protokoll.

1. Stelle die Rechnungsvorlage bereit

Verwende Python 3.10 oder neuer in einer aktivierten virtuellen Umgebung. Erstelle für dieses CLI-Deployment ein Connic-Projekt ohne verbundenes Git-Repository. Das Projekt benötigt Guthaben für die Ausführung der Agenten und ihre Modellaufrufe. Führe die folgenden Befehle in einem Verzeichnis aus, in dem invoice-mcp noch nicht existiert.

connic login öffnet das Connic-Dashboard im Browser. Erstelle dort einen Projekt-API-Schlüssel, kopiere das angezeigte Login-Token und füge es bei der Abfrage im Terminal ein. Das Token enthält die Projekt-ID und den API-Schlüssel. Falls sich der Browser nicht öffnet, rufe die URL aus der CLI-Ausgabe auf.

pip install connic-composer-sdk
connic init invoice-mcp --templates=invoice
cd invoice-mcp
pip install -r requirements.txt
connic login
connic deploy

Öffne die Deployment-URL aus der CLI-Ausgabe und warte, bis das Deployment erfolgreich abgeschlossen und aktiv ist. Ein abgeschlossener CLI-Befehl bedeutet zunächst, dass das Deployment eingereicht wurde. Mit den Standardeinstellungen führt Connic vor der Aktivierung die enthaltenen Tests aus. Falls der Build oder ein Test fehlschlägt, prüfe zuerst die Deployment-Logs. Der Schnellstart beschreibt Deployments per CLI und Git. Projekte mit verbundenem Git-Repository verwenden ihren konfigurierten Deployment-Branch.

2. Verknüpfe den Extraktor mit einer MCP-Server-Verbindung

Öffne invoice-extractor in der Umgebung mit dem aktiven Deployment. Wähle im Verbindungsdiagramm Add inbound connector, danach Create New Connector und MCP Server. Wähle Sync (Wait for Result), lass die Authentifizierung aktiviert und erstelle die Verbindung. Verknüpfe für dieses Beispiel nur den Extraktor.

Kopiere die Endpoint-URL und das Secret aus den Verbindungsdetails. Verwende die vollständige generierte URL einschließlich der Verbindungs-ID. Dieses Secret authentifiziert Aufrufe an der Verbindung. Das Projekt-Login-Token aus Schritt 1 ist ein separater Zugangsschlüssel. Der Endpoint akzeptiert einen Authorization: Bearer-Header oder X-Connic-Secret. Die Dokumentation zur MCP-Server-Verbindung beschreibt die Konfiguration.

Ein nativer oder serverseitiger MCP-Client muss entfernte HTTP-Verbindungen und einen eigenen Authentifizierungs-Header unterstützen, um diesen Endpoint zu nutzen. Die Verbindung verwendet ein gemeinsames Secret und bietet keine Anmeldung per OAuth. Browseranfragen mit einem Origin-Header werden abgewiesen. Der folgende Terminal-Client ruft die Verbindung direkt auf.

3. Ermittle invoice_extractor mit Python

Speichere den folgenden Code als mcp_invoice.py. Er verwendet die Python-Standardbibliothek und die von Connic unterstützte Protokollversion 2026-07-28. Jede Anfrage enthält Protokollmetadaten und passende HTTP-Header. Dieses Diagnoseskript liest die JSON-Antworten, die Connic für diese Methoden in der genannten Version zurückgibt. Ein allgemeiner MCP-Client muss auch andere Antwortformen verarbeiten können. Die Streamable-HTTP-Spezifikation legt die Anforderungen an den Transport fest.

import json
import os
from urllib.error import HTTPError
from urllib.request import Request, urlopen

endpoint = os.environ["MCP_ENDPOINT"]
secret = os.environ["MCP_SECRET"]
protocol_version = "2026-07-28"


def request(method, params, request_id):
    params = {
        **params,
        "_meta": {
            "io.modelcontextprotocol/protocolVersion": protocol_version,
            "io.modelcontextprotocol/clientInfo": {
                "name": "invoice-tutorial",
                "version": "1.0.0",
            },
            "io.modelcontextprotocol/clientCapabilities": {},
        },
    }
    headers = {
        "Authorization": f"Bearer {secret}",
        "Content-Type": "application/json",
        "Accept": "application/json, text/event-stream",
        "MCP-Protocol-Version": protocol_version,
        "Mcp-Method": method,
    }
    if method == "tools/call":
        headers["Mcp-Name"] = params["name"]
    body = {"jsonrpc": "2.0", "id": request_id,
            "method": method, "params": params}
    http_request = Request(endpoint, json.dumps(body).encode(), headers)
    try:
        with urlopen(http_request, timeout=310) as response:
            data = json.load(response)
    except HTTPError as error:
        raise RuntimeError(
            f"HTTP {error.code}: {error.read().decode()}"
        ) from error
    if "error" in data:
        raise RuntimeError(data["error"])
    result = data["result"]
    if result.get("isError"):
        raise RuntimeError(result["content"])
    return result


tools = request("tools/list", {}, 1)["tools"]
tool = next(tool for tool in tools if tool["name"] == "invoice_extractor")
print(json.dumps(tool, indent=2))

Die MCP-Tool-Methoden trennen das Ermitteln der Tools von ihrer Ausführung: tools/list beschreibt die verfügbaren Tools, tools/call ruft eines davon auf. Connic wandelt den Agentennamen invoice-extractor in invoice_extractor um. Die ausgegebene Tool-Definition enthält ein inputSchema mit dem Pflichtfeld message vom Typ String und einem optionalen Objekt payload.

Dieses Tool-Schema beschreibt die Anfrage an den Agenten. Das Rechnungsschema der Vorlage steuert dessen Ausgabe innerhalb von Connic. Die MCP-Verbindung veröffentlicht es weder als MCP-outputSchema noch gibt sie ein Feld structuredContent zurück.

4. Rufe das Tool mit einer Beispielrechnung auf

Hänge diesen Code an dieselbe Datei an. Er sendet eine fiktive Rechnung als payload.text. Connic übernimmt die Payload-Felder in die Agenteneingabe. Der Extraktor erhält deshalb message und text auf der obersten Ebene.

invoice_text = (
    "Example Supplier, invoice INV-001. "
    "Issued 2026-09-11, due 2026-09-25. "
    "Consulting: 2 hours at EUR 100, line total EUR 200. "
    "Subtotal EUR 200. Tax 19%: EUR 38. Total EUR 238."
)
result = request("tools/call", {
    "name": "invoice_extractor",
    "arguments": {
        "message": "Extract the invoice fields and check the arithmetic.",
        "payload": {"text": invoice_text},
    },
}, 2)

invoice = json.loads(result["content"][0]["text"])
print(json.dumps(invoice, indent=2))
expected = {"currency": "EUR", "subtotal": 200, "tax_amount": 38, "total": 238}
for field, value in expected.items():
    if invoice.get(field) != value:
        raise ValueError(f"Unexpected {field}: {invoice.get(field)!r}")

Ersetze beide Platzhalter durch die Verbindungsdetails aus Schritt 2. Führe die Datei in einer Shell aus, die export unterstützt. Bewahre das Secret in der lokalen Umgebung auf und übernimm es weder in Quelldateien noch in geteilte Protokolle.

export MCP_ENDPOINT='<endpoint-url>'
export MCP_SECRET='<connection-secret>'
python mcp_invoice.py

Im Sync-Modus gibt die Verbindung das Ergebnis zurück, sobald der Agent fertig ist. Sie wartet höchstens fünf Minuten. Für den Extraktor gilt weiterhin sein eigenes Timeout von 45 Sekunden. Die Hilfsfunktion prüft HTTP-Fehler, JSON-RPC-Fehler und result.isError, bevor sie den Inhalt zurückgibt. Bei einer erfolgreichen Extraktion enthält result.content[0].text das Rechnungs-JSON als String. Der zweite Codeblock decodiert diesen String.

5. Prüfe die extrahierten Felder und den Ausführungs-Trace

Die Beispielrechnung lässt sich nachrechnen: Zwei Stunden zu je 100 EUR ergeben 200 EUR netto. Bei 19 % Steuer kommen 38 EUR hinzu, der Gesamtbetrag beträgt 238 EUR. Das Skript prüft diese Zahlenfelder und die Währung. Vergleiche auch den ausgegebenen Lieferanten, die Rechnungsnummer, die Datumsangaben und die Positionen mit der Eingabe. Die erwarteten Werte ergeben sich aus der Beispielrechnung. Ein KI-Modell übernimmt die Extraktion; prüfe deshalb die Ausgabe auch dann, wenn der Tool-Aufruf erfolgreich ist.

Öffne die Agentenausführung im Dashboard und prüfe die empfangene Eingabe, die Aufrufe der Rechentools, die Ausgabe und mögliche Fehler. Der Leitfaden zu Ausführungen und Traces erklärt die Ansicht. Falls das Beispiel fehlschlägt, hilft die Fehlerart bei der Eingrenzung:

• HTTP 401 deutet auf ein Problem mit dem Verbindungs-Secret oder dem Authentifizierungs-Header hin.
• Ein fehlendes Tool oder StopIteration bedeutet, dass die Tool-Liste invoice_extractor nicht enthält. Prüfe den Endpoint, den verknüpften Agenten und dessen Namen.
• Prüfe bei einem Protokollfehler die Protokollversion, die Methoden-Header und die Metadaten der Anfrage gemeinsam.
• isError: true meldet eine fehlgeschlagene Ausführung oder ein Timeout. Prüfe den zurückgegebenen Fehler und den Trace des Agenten.
• Prüfe bei einem JSON-Decodierungsfehler oder einem unerwarteten Rechnungsfeld den zurückgegebenen Text und die Ausgabe des Extraktors.

Die Pipeline für eine Zusammenfassung der Prüfung

Verknüpfe invoice-pipeline, um ein zweites Tool namens invoice_pipeline bereitzustellen. Diese Sequenz extrahiert zuerst die Rechnungsfelder und führt danach den deterministischen Validator aus. Ihr Endergebnis fasst die Prüfung zusammen. Passe daher das Parsen und die Prüfungen im Client an dieses Ergebnis an. Der Validator meldet rechnerische Abweichungen. Er prüft nicht, ob ein Lieferant oder eine Rechnung echt ist.

Behalte Sync bei, wenn der Aufrufer das Ergebnis in derselben Anfrage benötigt. Im Inbound-Modus erhält er eine Ausführungs-ID, während der Agent im Hintergrund arbeitet. Für Anwendungen, die Rechnungstext über gewöhnliches HTTP senden, beschreibt die Anleitung zum Rechnungs-Webhook denselben Extraktor mit einer HTTP-Verbindung.