Google verwendet KI-Technologie, um Inhalte in Ihre bevorzugte Sprache zu übersetzen. KI-Übersetzungen können Fehler enthalten.

Integrationsstandards für verbundene MCP-Apps

Der MCP-Server stellt das Framework für die Verbindung der Funktionen Ihrer App (MCP-Tools) mit der Connected Apps Platform bereit. Damit die Ergebnisse Ihres Dienstes zuverlässiger ausgewählt, aufgerufen und verarbeitet werden können, muss Ihre MCP-Konfiguration die folgenden Standards strikt einhalten.

Grundprinzipien

Konzentrieren Sie sich bei jeder Funktion auf die Nutzerabsicht und die Anwendungsfälle und nicht auf die Funktionen der Funktion. Die Beschreibung ist die wichtigste Möglichkeit, dem Modell mitzuteilen, wofür Ihr Tool gedacht ist und auf welche Anwendungsfälle es reagieren kann.

Versionsverwaltung

Um skalierbare und robuste MCP-Bereitstellungen zu unterstützen, sollten Sie eine strukturierte URI-Architektur mit pfadbasierter Versionsverwaltung verwenden, z. B. /v1, /v2. So können Sie die Abwärtskompatibilität aufrechterhalten und neue Funktionen freigeben. Durch die Ergänzung mit anbieterspezifischen Subdomains wie https://gemini.mcp.company.com/mcp/v1 wird eine detaillierte Traffic-Verwaltung und die Optimierung von Tooldefinitionen ermöglicht, die auf den individuellen Kontext und das Verarbeitungsverhalten verschiedener KI-Modelle zugeschnitten sind.

Kompatibilität der MCP-Protokollversionen

Die Connected Apps Platform unterstützt die Spezifikation des Model Context Protocol (MCP) bis Version 2025-11-25. Neuere Spezifikationsversionen werden noch nicht unterstützt.

Verantwortung des Entwicklers: Sie sind dafür verantwortlich, dass Ihr MCP-Server während des initialize-Handshakes und bei allen Tool- und Schemadefinitionen strikt eine Protokollversion einhält, die von der Connected Apps Platform (2025-11-25) unterstützt wird.
Abwärtskompatibilität der Plattform: Da die Connected Apps Platform in Zukunft neuere MCP-Spezifikationsversionen übernimmt, bleibt unser Client abwärtskompatibel mit zuvor unterstützten Protokollversionen, sodass bestehende Produktionsintegrationen ohne Unterbrechung funktionieren.
Upgrades verwalten: Wenn Sie eine neu unterstützte MCP-Spezifikation übernehmen oder Schemaänderungen einführen möchten, stellen Sie diese Aktualisierungen über einen neuen versionierten URI-Pfad (z. B. /mcp/v2) bereit, während Sie Ihren vorhandenen Endpunkt (/mcp/v1) für aktiven Traffic beibehalten.

Änderungen an MCP-Schemas sind zwischen App-Versionen zulässig. Wir empfehlen, diese Funktion zu nutzen und die MCP-Endpunkte zu versionieren, um eine schrittweise Einführung neuer Funktionen zu ermöglichen, oder sich strikt auf abwärtskompatible Änderungen zu verlassen.

Spezifikation des Transportprotokolls

Die Connected Apps Platform unterstützt ausschließlich die Streamable HTTP-Transport-Spezifikation des Model Context Protocol Version 2025-03-26 und höher. Das Legacy-HTTP mit SSE-Transport, das in der Spezifikation vom 05.11.2024 beschrieben wird, wird nicht unterstützt.

Einzelner HTTP-Endpunkt. Der in der Connected Console angegebene MCP-Endpunkt (z. B. https://api.example.com/mcp) ist die einzige URL, an die entsprechende Google-Produkte alle JSON-RPC-Anfragen (initialize, tools/list, tools/call) über Standard-HTTP POST senden.
SSE-Streaming innerhalb von streamfähigem HTTP. Der Legacy-SSE-Transport mit mehreren Endpunkten wird nicht unterstützt, aber Server-Sent Events wie text/event-stream werden in Streamable HTTP unterstützt. Ausgehende Anfragen von entsprechenden Google-Produkten enthalten Accept: application/json, text/event-stream. Das bedeutet, dass Ihr Server entweder eine Standard-application/json-Nutzlast zurückgeben oder inkrementelle Antworten mit Content-Type: text/event-stream direkt im HTTP POST-Antworttext streamen kann.
GET-Stream und 405 Method Not Allowed. Clients können einen optionalen GET-Stream auf dem Endpunkt für Server-zu-Client-Benachrichtigungen versuchen. Wenn Ihr Server zustandslos ist oder nur Anfragen und Antworten verarbeitet, wird die Rückgabe von HTTP 405 Method Not Allowed explizit unterstützt und vom Client-Proxy des entsprechenden Google-Produkts sauber verarbeitet.

Anleitung für Server

Die Connected Apps Platform ist für die Aufnahme von Serveranweisungen optimiert. Dadurch ist ein gewisses Maß an Kontrolle über das Verhalten des Modells möglich, das auf andere Weise nicht erreicht werden kann.

Folgen Sie der Anleitung für den Server.

Als „Modellhinweis“ mit Nutzungskontext behandeln

Beachten Sie die folgenden Richtlinien, wenn Sie Modellen Hinweise geben.

Schreiben Sie Anweisungen als allgemeinen „Hinweis“ oder Leitfaden, damit das LLM den allgemeinen Zweck und die Funktionen des Servers versteht.
Beschreiben Sie, was der Server tun kann, anstatt Funktionen aufzulisten oder zu beschreiben, wie das Modell die Tools und Ressourcen des Servers verwenden soll. Wenn das Modell das „Was“ richtig versteht, kann es das „Wie“ anhand der User Journey recht gut bestimmen.
Gehen Sie davon aus, dass dieser Text direkt dem System-Prompt des Modells hinzugefügt wird. Formulieren Sie klar, direkt und token-effizient.

Ergänzen, nicht duplizieren

Verwenden Sie diesen Bereich für globalen Kontext, der für alle Tools gilt, um Redundanz mit einzelnen Toolbeschreibungen zu vermeiden.

Beispiele für Serveranweisungen

Die folgenden Beispiele zeigen, was Sie beim Schreiben von Serveranweisungen tun und lassen sollten.

Empfohlen	Nicht empfohlen
Du bist ein spezialisierter GitHub-Repository-Maintainer. Dieser Server bietet umfassenden Zugriff auf Repository-Metadaten, Issue Tracker und PR-Workflows. Verwenden Sie es, um den Zustand des Projekts zu erhalten, die Triage zu automatisieren und Codestandards zu gewährleisten. Sofern nicht anders angegeben, werden alle Aktionen im Kontext der authentifizierten Organisation ausgeführt. Priorisieren Sie die Identifizierung veralteter Threads oder nicht verknüpfter PRs, um das Repository organisiert zu halten. Prägnant, direkt und ergänzend zum Modell Definiert das „Was“ (Projektzustand, Triaging) und nicht das „Wie“ Erwähnt den Authentifizierungsbereich, der für alle Tools gilt	Dieser Server hat Tools für GitHub. Du solltest das Tool `list_issues` verwenden, wenn der Nutzer nach Problemen fragt. Sie können `create_pull_request` verwenden, um eine Pull-Anfrage zu erstellen. Verwenden Sie diese Tools sorgfältig, um dem Nutzer bei der Verwaltung seines Codes zu helfen. Prüfen Sie immer den Repository-Namen, bevor Sie ein Tool aufrufen. If the user asks for a summary, call the tools first and then summarize the output Listen Sie die Toolnamen nicht noch einmal auf, Sagen Sie dem Modell nicht, „wie“ es denken soll. Das kann im Widerspruch zur integrierten Logik des Modells stehen, die den Nutzerkontext verwendet, um die richtige Entscheidung zu treffen. erklärt nicht die Art des Serverzugriffs oder seine spezifischen Einschränkungen)

Richtlinien für Tools

In den folgenden Richtlinien werden Best Practices für das Erstellen von MCP-Serverkonfigurationen für verschiedene Funktionen oder Tools in Ihrer App beschrieben.

Namenskonventionen für Tools

Beachten Sie die folgenden Richtlinien für die Benennung Ihres Tools:

Verwenden Sie intuitive, menschenlesbare Namen.

Verwenden Sie menschenlesbare Namen mit klarer, intuitiver Bedeutung anstelle von mehrdeutigen Namen. get_user_information ist beispielsweise einfacher als userInfo.

Achten Sie auf die richtige Groß-/Kleinschreibung.

Beachten Sie die folgenden Regeln für die Groß-/Kleinschreibung von Toolfunktionsnamen und App-Triggern:

Groß-/Kleinschreibung bei Toolfunktionen Verwenden Sie snake_case oder camelCase für Toolfunktionsnamen, die in Ihrem MCP-Schema definiert sind (z. B. get_user_information oder publishDraft).
Gehäuse des App-Ziehpunktes Bei App-Triggern und Erwähnungen (z. B. @MyTwoWordApp) wird die Groß-/Kleinschreibung nicht berücksichtigt. Die Plattform normalisiert Nutzereingaben in Kleinbuchstaben (@mytwowordapp), PascalCase (@MyTwoWordApp) und camelCase (@myTwoWordApp).
Formatierung des Anzeigenamens: Registrieren Sie den offiziellen Titel Ihrer App mit PascalCase oder Standardleerzeichen, damit er in UI-Elementen gut lesbar ist.
Umgang mit Tippfehlern: Während Groß- und Kleinschreibung automatisch berücksichtigt wird, werden Tippfehler (z. B. @mytwowrodapp) nicht durch direkten Stringabgleich, sondern durch die Erkennung von Fallback-Intents erkannt. Entwickler sollten in der Dokumentation auf die korrekte Schreibweise von Handles achten.

Explizite Verb-Nomen-Benennung verwenden

Verwenden Sie spezifische verb_noun-Namen und vermeiden Sie Mehrdeutigkeiten. publish_draft ist beispielsweise besser als handle_content.

Detaillierungsgrad des Tools

Beachten Sie die folgenden Richtlinien zur Tool-Granularität.

Tools als atomare Endpunkte behandeln

Behandeln Sie Tools als atomare Endpunkte ohne interne Tool-Bedingungen oder mehrere Funktionen mit den jeweils erforderlichen Parametern. Mit granularen Tools kann das Modell Schritte logisch verketten, was Halluzinationen reduziert.

Flachere Schemas verwenden

Wenn Sie tief verschachtelte Objekte oder komplexe oneOf- oder anyOf-Schemalogik benötigen, um Eingaben zu validieren, ist Ihr Tool wahrscheinlich zu breit gefächert.

Schutzmaßnahmen für Voraggregation und Nutzlast beachten

Obwohl die Vorabaggregation von Daten für kleine, begrenzte Nutzlasten nicht strikt durch das Protokoll erzwungen wird, ist sie in der Praxis dringend erforderlich, wenn mit großen Datensätzen, Längsschnittverläufen und Datensätzen aus mehreren Quellen gearbeitet wird. Die Connected Apps Platform erzwingt Schutzmaßnahmen in Bezug auf Kontextfensterlimits, Ausführungslatenz und Modell-Reasoning-Schritte. Beachten Sie die folgenden Richtlinien, um diese Schutzmaßnahmen einzuhalten:

Filtern und Zusammenfassen im Backend Filtern, aggregieren oder fassen Sie große Datenstreams auf Ihrem MCP-Server immer vor, bevor Sie Antworten an die entsprechenden Google-Produkte zurückgeben.
Rohdaten vermeiden: Geben Sie niemals Rohdatenbankzeilen oder vollständige nicht indexierte Logs in die Rückgabe-Nutzlast des Tools ein.

Interne und Meta-Tools weglassen

Geben Sie in der tools/list-Antwort Ihres Servers nur modellbezogene Funktionen an:

Hilfstools filtern: Lassen Sie alle internen, administrativen oder Meta-Tools weg, die nicht vom Modell aufgerufen werden sollen (z. B. Server-Systemdiagnosen, interne Einrichtungsroutinen oder Entwickler-Hilfsprogramme).
Effizienz des Kontextfensters: Wenn Sie unnötige Tools ausschließen, bleibt Ihr MCP-Schema kompakt, der Tokenverbrauch im Kontextfenster wird reduziert und Verwirrung bei der Tool-Weiterleitung des Modells wird vermieden. MCP-Server, die Dutzende von Tools oder tief verschachtelte „Mega-Tool“-Schemas bereitstellen, werden bei der Überprüfung zur Behebung gekennzeichnet.

Empfohlene und zu vermeidende Vorgehensweisen für die Granularität des Tools

Die folgenden Beispiele zeigen, was Sie bei der Benennung von Tools und der Verwendung von Granularität tun und lassen sollten.

Empfohlen	Nicht empfohlen
Spezifische Tools mit klaren Namen und Parametern Das Eingabeschema für jedes Tool ist strikt. Wenn das LLM einen Nutzer erstellen möchte, muss es eine E-Mail-Adresse angeben. Wenn es löschen möchte, muss es eine ID angeben. Es gibt kein Rätselraten. `... @mcp.tool() def create_user(email: str, role: str = "viewer") -> str: """Register a new user. Returns the new User ID.""" # Logic is purely creation return "user_123" @mcp.tool() def delete_user(user_id: str) -> str: """Permanently remove a user by their ID.""" # Logic is purely deletion return f"User {user_id} deleted" @mcp.tool() def update_user_role(user_id: str, new_role: str) -> str: """Change an existing user's permission level.""" return f"User {user_id} is now {new_role}" ...`	Toolname: manage_user Description: "Use this tool to create, update, delete, or retrieve users." ... @mcp.tool() def manage_user( action: Literal["create", "update", "delete", "get"], user_id: Optional[str] = None, email: Optional[str] = None, role: Optional[str] = "viewer" ) -> str: """ Use this to manage users. WARNING: logic is hidden inside Python, not visible in the schema. """ if action == "create": if not email: return "Error: Email required for creation" # Runtime error, not schema error return f"Created user {email}" elif action == "delete": if not user_id: return "Error: User ID required" return f"Deleted {user_id}" return "Action completed" """ ...

Tool-Anmerkungen für die Sicherheit deklarieren

Konfigurieren Sie Protokollannotationen in Ihren Tooldefinitionen, um das Ausführungsverhalten zu vermitteln und integrierte Sicherheitsprüfungen in den entsprechenden Google-Produkten auszulösen:

Bestätigungs-Gates zur Laufzeit: In den entsprechenden Google-Produkten werden annotations.destructiveHint: true und annotations.openWorldHint: true als wichtige Flags verwendet, um Bestätigungsaufforderungen für Nutzer zur Laufzeit auszulösen. Deklarieren Sie destructiveHint: true für zustandsändernde, schreibende oder destruktive Aktionen und legen Sie openWorldHint: true für Tools fest, die mit Open-World- oder externen Umgebungen interagieren, damit die Oberfläche den Nutzer vor der Ausführung nativ zur Bestätigung auffordert.
Hinweis für schreibgeschützte Abfragen: Legen Sie readOnlyHint: true für Abfragetools fest, die nur Daten abrufen, ohne den Backend-Status zu ändern.
Explizite Annotationsstandardwerte: Gemäß der Spezifikation des Model Context Protocol führt das Weglassen von readOnlyHint dazu, dass Clients aus Sicherheitsgründen standardmäßig readOnlyHint: false und destructiveHint: true annehmen. Durch die explizite Deklaration von Annotationen für alle Tools wird ein vorhersehbares Modell-Routing und eine ordnungsgemäße Ausführungssicherheit gewährleistet.

Toolbeschreibungen

Die Beschreibung ist der einzige Kontext, den das Modell hat, um zu entscheiden, ob Ihr Tool das aktuelle Problem lösen kann. Beachten Sie beim Verfassen von Beschreibungen die folgenden Richtlinien:

Anweisungen schreiben, keine Kommentare

Schreiben Sie Toolbeschreibungen als Anweisungen und nicht als Codekommentare, die oft passiv sind. LLMs reagieren gut auf Anweisungen.

Das „Wie“ erklären

Eine gute Beschreibung schließt die Lücke zwischen „Ich habe ein Tool“ und „Ich weiß, wie ich dieses Tool in eine Unterhaltung einbinde“.

Erklären Sie das „Warum“

Unterscheiden Sie dieses Tool von ähnlichen Tools, z. B. „Verwenden Sie dieses Tool für interne Nutzer und customer_update für externe Nutzer“.

Link angeben

Teilen Sie dem Modell mit, wo die Argumente zu finden sind, z. B. „aus dem Tool order_search“.

Format angeben

Geben Sie Einheiten (Meter oder Fuß) und Formate (ISO-Daten, semantische Versionen) an.

Modellermessen vermeiden

Weisen Sie das Modell nicht an, nach „bestem Wissen und Gewissen“ zu handeln, und schlagen Sie keine optionalen, ungesteuerten Aktionen vor.

Beispiele für Toolbeschreibungen

Die folgenden Beispiele zeigen, was Sie beim Schreiben von Toolbeschreibungen tun und lassen sollten.

Empfohlen	Nicht empfohlen
Informationsquelle "Updates a user's email. Sie müssen die UUID „id“ verwenden, die vom Tool `search_users` zurückgegeben wird. Leiten Sie Nutzer-IDs nicht ab und erraten Sie sie nicht.“ (Die Ausgabe eines Tools wird explizit mit der Eingabe dieses Tools verknüpft.)	„Aktualisiert die E‑Mail-Adresse des Nutzers.“ (Das Modell könnte eine ID wie 12345 erraten.)
Format und Einschränkung „Plane eine Besprechung. „date“ muss im ISO 8601-Format (JJJJ-MM-TT) angegeben werden. Wenn der Nutzer „morgen“ oder einen anderen relativen Bezug verwendet, berechne das Datum basierend auf dem aktuellen Kontext.“	„Plane eine Besprechung für das angegebene Datum.“ (sieht für einen Menschen korrekt aus, z. B. „morgen“, schlägt aber bei der Schemavalidierung fehl, da „2025-10-12“ erforderlich ist)
Erwartungen an die Ausgabe "Retrieves server logs. Gibt die letzten 50 Zeilen des Rohtexts zurück. Fordern Sie für die Analyse kleinere Zeitfenster an, um Tokenlimits zu vermeiden.“	Server-Logs abrufen (Das Modell ruft möglicherweise ein Tool auf, das eine Zusammenfassung erwartet, erhält einen rohen 5‑MB-JSON-Dump und liefert möglicherweise eine schlechte Nutzererfahrung.)
`@mcp.tool() def update_campaign_status(campaign_id: str, status: str) -> str: """ Promotes or pauses an advertising campaign. CRITICAL USAGE RULES: 1. 'campaign_id': Must be the 32-character UUID retrieved from 'list_campaigns'. 2. 'status': Must be exactly one of: ['active', 'paused', 'archived']. Returns: A confirmation string with the new status and timestamp. """ # Logic... ...` Diese Beschreibung dient als Kurzanleitung. Sie verarbeitet die Quelle (wo die ID abgerufen werden soll), die Einschränkungen (gültige Enums) und die Aktion.	`@mcp.tool() def update_campaign_status(id: str, status: str) -> str: """ Updates the campaign status in the database. """ # Logic...` Hierbei wird die gesamte Arbeit von den Variablennamen erledigt. Das Modell muss die gültigen Werte für „status“ erraten.

Toolparameter

Beschreiben Sie neben dem Tool selbst auch die Parameter, um sie eindeutig zu machen.

Explizite Typen

Verwenden Sie starke, spezifische Typen (string, integer, boolean, array).

Enums für feste Wertesätze verwenden

Wenn ein Parameter nur einen festen Satz von Werten akzeptiert (z. B. daylight, cool, warm), listen Sie sie in einem enum-Array auf. Dadurch wird die Genauigkeit erheblich verbessert.

Erforderliche Parameter klar angeben

Definieren Sie klar, welche Parameter für die Funktion erforderlich sind.

Semantischen Schemaabgleich anwenden

Beim Einbinden Ihrer App ist möglicherweise ein semantischer Schemaabgleich zwischen den Parametern Ihrer Tools und der Branche, für die Sie entwickeln, erforderlich. Sie erhalten das erwartete vertikale Schema (ein JSON-Schema) während des Onboarding-Prozesses.

Beispiele für Toolparameter

Die folgenden Beispiele zeigen, was Sie beim Umgang mit Toolparametern tun und lassen sollten.

Empfohlen	Nicht empfohlen
Argumentformate und ‑einheiten radius: "Der Radius in Metern. Muss eine Gleitkommazahl > 0 sein.“ (verhindert KI-Halluzinationen bei Einheiten)	radius: „Der Radius des Kreises.“
ID-Formate und Kontext user_id: "Die Datenbank-UUID (z. B. 550e8400-e29b...). Verwenden Sie hier keine E‑Mail-Adressen.“ Hinweis: Als Best Practice sollten alle numerischen ID-Felder als Stringwerte behandelt werden. Wenn Ihre ID mehr als 10 Ziffern hat, besteht die Gefahr, dass sie von internen Systemen abgeschnitten wird (erzwungene Speicherung in einem 32-Bit-Container) und diese Version vom Modell in zukünftigen Toolaufrufen verwendet wird. (verhindert Typfehler)	user_id: „Die ID des Nutzers.“
Erwartungen an den Rückgabewert "Updates the record and returns the updated JSON object including the new timestamp." (Teilt dem Modell mit, dass es nach dem „update“ nicht sofort ein „get“-Tool aufrufen muss, um die Änderung zu prüfen.)	„Aktualisiert den Eintrag.“
`@mcp.tool() def search_logs(query: str, limit: int = 10) -> str: """ Searches server error logs using Lucene syntax (e.g. 'level:ERROR AND service:auth'). Args: query: A Lucene-formatted search string. limit: Max results to return. capped at 50. Returns: A formatted string of log entries with timestamps. """ ...`	`@mcp.tool() def search_logs(query: str, limit: int = 10) -> str: """Searches the logs.""" ...` Das LLM weiß nicht, welche Syntax „query“ unterstützt (SQL? Regex? Nur-Text?) Das maximale Limit ist nicht bekannt.

Antworten und Fehlerbehandlung

Gemäß dem Grundprinzip Die Antwort ist der nächste Prompt meldet das Tool das Ergebnis seiner zugrunde liegenden Ausführung, indem es eine Datennutzlast zurückgibt, die dann direkt in das Kontextfenster des LLM eingefügt wird. Der Erfolg oder Misserfolg des Ergebnisses bestimmt, was als Nächstes passiert:

Wenn der Aufruf erfolgreich ist: Das Modell benötigt den Rückgabewert, um zu wissen, was passiert ist, und den nächsten Schritt zu entscheiden.
Wenn es fehlschlägt: Das Modell muss wissen, warum es fehlgeschlagen ist und wie das Problem behoben werden kann. Ein Absturz (500-Fehler) beendet die Unterhaltung. Eine aussagekräftige Fehlermeldung ermöglicht es dem Modell, sich selbst zu korrigieren.

Unabhängig davon, ob die zugrunde liegende Logik Ihres Tools erfolgreich ist oder fehlschlägt, müssen Sie die Nutzlast des Rückgabewerts so formatieren, dass das Modell sie leicht parsen kann. Beachten Sie beim Verpacken der Antwortnutzlast die folgenden Best Practices.

JSON verwenden

Strukturierte Daten in TextContent formatieren (vorübergehende Einschränkung). Da structuredContent auf der Connected Apps Platform noch nicht unterstützt wird, müssen Sie Ihre Daten manuell serialisieren. Auch wenn Sie eine einfache Liste zurückgeben, json.dumps() Sie sie.

URLs in Antwort einbeziehen

Die zurückgegebenen URLs sollten relativ kurz sein und nicht viele Parameter enthalten. Es wird empfohlen, URL-Kürzungsdienste zu verwenden, um Tokens zu sparen und das Risiko von Halluzinationen zu verringern.

Selbstbeschreibende Anti-Halluzinations-Nutzlasten

Verknüpfen Sie Rohcodes oder interne IDs immer mit menschenlesbaren Anzeigenamen, expliziten Maßeinheiten und Referenzbereichen. Geben Sie niemals komprimierte Wörterbuchschlüssel oder nicht zugeordnete numerische Codes zurück, die das Modell dazu zwingen, den Kontext abzuleiten.

Robuste Fehlerbehandlung implementieren

Geben Sie klare, aussagekräftige Fehlermeldungen zurück, damit das Modell versteht, was schiefgelaufen ist, und den Nutzer informieren kann. Weitere Informationen finden Sie unter MCP-Fehlerbehandlung.

try/except verwenden

Verpacken Sie die Tool-Logik in try/except-Blöcke und geben Sie Fehler als Strings zurück.

Fehler mit Lösungsvorschlägen bereitstellen

Schlagen Sie in der Fehlermeldung den nächsten Schritt vor (z. B. „Versuchen Sie es zuerst mit Tool X“).

Aktionen bestätigen

Geben Sie für Tools mit Nebenwirkungen (Erstellen/Aktualisieren/Löschen) keine leeren Strings zurück.

Beispiele für Antworten und Fehlerbehandlung

Die folgenden Beispiele zeigen, was Sie bei Antworten und der Fehlerbehandlung tun und lassen sollten.

Empfohlen	Nicht empfohlen
Explizite Serialisierung `... import json @mcp.tool() def query_metrics(metric_id: str) -> str: result = {"id": metric_id, "value": 42, "unit": "ms"} # GOOD: Returns '{"id": "cpu", "value": 42}' -> Valid JSON return json.dumps(result, indent=2)`	`... @mcp.tool() def query_metrics(metric_id: str) -> str: result = {"id": metric_id, "value": 42, "unit": "ms"} # BAD: Returns "{'id': 'cpu', 'value': 42}" -> Invalid JSON return str(result)`
Abfangen und informieren `... @mcp.tool() def get_user_details(user_id: str) -> str: try: user = db.get_user(user_id) if not user: # GOOD: Informative error returned as content return f"Error: User with ID '{user_id}' not found. Please verify the ID using 'search_users'." return json.dumps(user) except Exception as e: return f"Error: Database connection failed ({str(e)}). Please try again later."` (Das Tool „funktioniert“ technisch gesehen, d. h., es gibt einen String zurück, aber der String enthält die Fehlerdetails. Das Modell liest dies, erkennt, dass die ID nicht existiert, und kann den Nutzer nach der richtigen ID fragen.	`... @mcp.tool() def get_user_details(user_id: str) -> str: # BAD: Unhandled exception if ID not found user = db.get_user(user_id) return json.dumps(user)` (Wenn `get_user` fehlschlägt, gibt der Server den Fehler 500 aus. Das LLM erhält einen allgemeinen Ausführungsfehler und weiß nicht, warum (War die ID falsch? Datenbank ausgefallen? Permission denied?). Es wird wahrscheinlich genau dieselbe fehlerhafte Eingabe noch einmal versuchen.)
Leere Antworten `... @mcp.tool() def post_story(story_content: str) -> str: service_name = "story_service" api_client.post("/stories", json={"content": story_content}) # GOOD: Explicit confirmation of state change. return f"Service '{service_name}' successfully posted content. Status is now 'posted'."`	`... @mcp.tool() def post_story(storyContent: str): subprocess.post(["postsrv", "story", storyContent]) # BAD: Returns null/empty string. Model is confused.` LLMs werden durch leere Antworten oft verwirrt. Sie könnten „Das Tool ist fehlgeschlagen“ halluzinieren oder den Aufruf einfach wiederholen.
Selbstbeschreibende Anti-Halluzinations-Nutzlast Verknüpfen Sie Rohcodes oder interne IDs immer mit menschenlesbaren Anzeigenamen, expliziten Maßeinheiten und normalen Referenzbereichen. `{"lab_code": "2345-7", "display_name": "Glucose [Mass/volume] in Blood", "value": 105, "unit": "mg/dL", "reference_range": "70-99 mg/dL"}` (So erfährt das Modell genau, was der Wert bedeutet, ohne dass es Einheiten oder Referenzschwellenwerte ableiten muss.)	Roh-IDs, benutzerdefinierte Komprimierung oder nicht zugeordnete Codes Rückgabe von internen Roh-IDs, benutzerdefinierten Wörterbuchabkürzungen oder numerischen Codes ohne Labels. `{"code": "2345-7", "v": 105}` (Das Modell muss raten, worauf sich 105 bezieht, was zu halluzinierten Einheiten, fehlendem Kontext oder ungenauen Erklärungen führt.)

MCP-Fehlerbehandlung

Es ist wichtig, Fehler angemessen zu behandeln.

Bei behebbaren Fehlern (z. B. ungültige Nutzer-ID oder fehlender optionaler Parameter) geben Sie in der Toolantwort einen normalen Textstring mit beschreibenden Fehlerdetails zurück. So kann das Modell das Feedback prüfen, verstehen, was schiefgelaufen ist, und sich selbst korrigieren oder den Nutzer um Klarstellung bitten.
Lösen Sie bei Terminalfehlern (z. B. Ratenbegrenzung, Authentifizierungs- oder Berechtigungsfehler oder Ausfälle von Backend-Servern) eine McpError mit dem entsprechenden Fehlercode aus, damit die Plattform den Fehler systematisch verarbeiten kann.

Beispiel für einen Fehlerantworttext (JSON)

{
  "jsonrpc": "2.0",
  "error": {
    "code": -32302,
    "message": "User permission denied for the requested operation.",
    "data": null
  },
  "id": 1
}

Message enthält einen JSON-Dump des Felds ErrorData des MCP. Wenn die richtigen code und die für das Modell sichtbaren message zurückgegeben werden, kann die Connected Apps Platform die Fehlermeldung lesen und dem Nutzer eine hilfreiche Erklärung in natürlicher Sprache zurückgeben. Beispiel: „Tut mir leid, ich konnte den Veranstaltungsort mit dieser ID nicht finden. Könnten Sie den Namen bitte überprüfen?“

Das MCP ermöglicht es Clients, sich über die JSON-RPC 2.0-Spezifikation mit MCP-Servern zu verbinden. JSON-RPC hat bestimmte vordefinierte Fehler, die bei häufig auftretenden Fehlern wie ungültigen Anfragen, Parsing-Fehlern usw. gesendet werden. In diesem Leitfaden wird beschrieben, wie MCP-Server benutzerdefinierte Fehler zurücksenden können.

Status Code	Nachricht	Nutzung	Muss explizit zurückgegeben werden?
Nutzer-/Kundenfehler
-32300	USER_RATE_LIMITED	Der Nutzer hat das maximale Nutzungslimit erreicht.	JA
-32301	MISSING_REQUIRED_INFORMATION	Die Eingabeanfrage enthält nicht alle erforderlichen Informationen	JA
-32302	USER_PERMISSION_DENIED	Der Nutzer hat die Berechtigung zur Verwendung des Tools verweigert. Beispielsweise kann es sein, dass Nutzer ein Arbeitskonto haben müssen, eine Altersbeschränkung gilt, ein bestimmter Standort erforderlich ist oder Nutzer kein Enterprise-Abo des Tools haben dürfen.	JA
Anwendungsfehler/Geschäftslogikfehler
-32400	RUNTIME_ERROR	Bei der Ausführung des Servercodes ist ein Fehler aufgetreten	JA
-32401	NULL_POINTER_EXCEPTION	Versuch, einen Nullzeiger oder ein Nullobjekt auszuführen	JA
-32402	OUT_OF_MEMORY	Nicht genügend Speicher im Servercode, um ihn einem Objekt zuzuweisen	JA
Infrastrukturfehler
-32500	DEADLINE_EXCEEDED	Die Anfrage dauert länger als zulässig. Kann viele Ursachen haben, z.B. überlasteter Server, Netzwerkprobleme usw.	JA
-32501	RESOURCE_EXHAUSTED	Der Server hat keinen Arbeitsspeicher, Speicherplatz, Threads, CPU-Zeit usw. mehr.	JA
-32502	SERVICE_UNAVAILABLE	Abhängiger Dienst (z.B. ein anderer Mikrodienst, eine Datenbank, ein Cache usw.) ist nicht verfügbar	JA
JSON-RPC-Fehler (diese Fehler sind Teil des MCP-Transports)
-32700	PARSE_ERROR	Die Anfrage konnte nicht auf dem Server geparst werden.	NEIN
-32600	INVALID_REQUEST	Fehlerhafte Clientanfrage	NEIN
-32601	METHOD_NOT_FOUND	Ungültiger MCP-Toolname	NEIN
-32602	INVALID_PARAMS	Ungültige Anfrageparameter, einschließlich fehlender Parameter oder nicht übereinstimmender Parametertypen	NEIN
-32603	INTERNAL_ERROR	Standardantwort	NEIN

Im Folgenden finden Sie ein Beispiel dafür, wie Sie mit dem offiziellen Python SDK (mcp) einen MCP-Fehler auf Ihrem Server auslösen können. Lösen Sie einen McpError mit einer ErrorData-Nutzlast aus, die vom SDK automatisch in das erforderliche JSON-RPC-Fehlerformat mit dem Fehlerstatus serialisiert wird.

from mcp import types
from mcp.shared.exceptions import McpError

@mcp.tool()
def foo_tool() -> list[types.TextContent]:
  """Always returns an error."""
  raise McpError(
    types.ErrorData(
        code=-32302, # USER_PERMISSION_DENIED
        message="Message to show to the model."
    ),
  )

Toolkontext

Anwendbare Google-Produkte unterstützen eine Tool Context API, um Signale an MCP-Server zu übergeben. Diese API wird in gültigen Anwendungsfällen verwendet, die vertrauliche Informationen erfordern, z. B. Metadaten, die nicht Teil der Kerndefinition des Tools sind, wie im Fall einer Sprache für Tools, die lokalisiert werden müssen. Die Tool Context API ist nur über die Connected Console verfügbar.

Wenn Sie ein Signal wie current_user_location_fine in der Connected Console für Ihre App registrieren, ergänzen die entsprechenden Google-Produkte MCP-Anfragen (tools/call) um einen zusätzlichen _meta-Eintrag mit den angeforderten Daten. Die folgenden Signale werden unterstützt:

current_user_location_fine (nur Gemini, für zulässige Branchen)
user_locale
current_user_location_coarse

{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "find-restaurant",
    "arguments": {"query": "restaurants near me"},
    "_meta": {
      "current_user_location_fine": {
        "latitude_degrees": 37.7749,
        "longitude_degrees": -122.4194,
        "accuracy_meters": 112.4221
      },
      "user_locale": {
        "language_code": "en",
        "region_code": "US"
      }
    }
  }
}

So entpacken Sie diese Daten:

from mcp.server.fastmcp import FastMCP

mcp = FastMCP("remote_mcp")

@mcp.tool()
async def find_restaurants(query: str, ctx: Context) -> str:
   # Access context directly from _meta
   request_context = ctx.request_context
   meta_dict = ctx.request_context.meta.model_dump() if ctx.request_context.meta else {}

   location_context = meta_dict.get("current_user_location_fine", {})
   lat = location_context.get("latitude_degrees")
   lng = location_context.get("longitude_degrees")
   if lat and lng:
       return f"Finding '{query}' near ({lat}, {lng})"
   return f"Finding '{query}' (no location provided)"

Rendering der UX

MCP-Apps

Anwendbare Google-Produkte unterstützen MCP-Anwendungsintegrationen für ausgewählte User Journeys, um benutzerdefinierte Benutzeroberflächen zu erstellen. Folgen Sie der Spezifikation, um allgemeine Integrationsanleitungen zu erhalten.

Für die Einbindung von MCP-Anwendungen in entsprechende Google-Produkte gelten die folgenden Einschränkungen.

Ressourcenaufnahme bei der Registrierung

Anwendbare Google-Produkte rufen UI-Ressourcen während der Toolaufnahme ab, ähnlich wie die Toolliste und die Toolbeschreibungen. Das bedeutet, dass Ressourcenaktualisierungen, z. B. Änderungen in JavaScript, nicht automatisch übernommen werden und die Tools neu aufgenommen werden müssen.

Eine einzelne UI-Ressource darf nicht größer als 15 MB sein und die kumulative Größe der UI-Ressourcen auf Ihrem Server darf 100 MB nicht überschreiten.

UI-Ressourcen müssen einen der unterstützten MIME-Typen verwenden: text/html, text/javascript, text/css oder text/html;profile=mcp-app. Nicht standardmäßige oder plattformspezifische MIME-Typen schlagen bei der Validierung fehl, wenn sie in die Vorschau übertragen werden.

Richtlinien für CSPs

Die entsprechenden Google-Produkte folgen der offiziellen MCP-Apps-Spezifikation, die CSP [1], [2] umfasst, und blockieren alle Anfragen, die gegen CSP-Anweisungen verstoßen.

Bei anwendbaren Google-Produkten müssen zusätzlich blob: und data: zur CSP hinzugefügt werden, falls verwendet. Diese werden nicht standardmäßig hinzugefügt. Es liegt im Ermessen der Entwickler, sie der CSP hinzuzufügen oder nicht.

„script-src“ ist eine Ausnahme

Die einzigen zulässigen Anweisungen sind: unsafe-inline (standardmäßig hinzugefügt), wasm-unsafe-eval und data: (falls in resource_domains enthalten). Wenn der iFrame externe Skripts lädt, kann dies entweder durch das Bündeln von JS in HTML oder durch die Verwendung eines SRI-Hashs (Subresource Integrity) gelöst werden.

Option 1: JS inline in HTML einfügen / bündeln (am einfachsten)
- JS-Code bündeln:
  - Fügen Sie den Inhalt von component-init.js direkt in <script>-Tags in der HTML-Nutzlast ein, die für die UI-Ressource zurückgegeben wird:
```
<script>
// Paste component-init.js content directly here
</script>
```
- Remote-<script src>-Tags entfernen
  - Löschen Sie <script src="https://api.mycompany.com/...">-Verweise aus dem HTML-Dokument.
- Tool zum erneuten Importieren/Aktualisieren
Option 2: SRI-Hash (Subresource Integrity) verwenden:

Verwenden Sie diese Option, wenn das Script extern unter https://api.company.com/... gehostet bleiben muss.
- SHA-256-Hash des Skripts berechnen
  - Base64-SHA-256-Hash von component-init.js generieren
- Fügen Sie den Hash zu resourceDomains hinzu (muss das Präfix sha256- enthalten, um mit dem Attribut integrity übereinzustimmen).
- HTML-Tag <script> aktualisieren
  - Fügen Sie dem Script-Tag im HTML-Widget die Attribute integrity und crossorigin hinzu.
- CORS-Header auf CDN/Server prüfen
  - Achten Sie darauf, dass api.company.com component-init.js mit Access-Control-Allow-Origin: * bereitstellt (oder scf.usercontent.goog zulässt), damit der Browser den Antworttext für die SRI-Überprüfung lesen kann.
- Tool zum erneuten Importieren/Aktualisieren

Sicherheitsrichtlinien für die Beschreibung von MCP-Tools

Da die Beschreibung der einzige Kontext ist, den das Modell hat, um die Funktionen des Tools zu verstehen, muss sie genau und sicher formuliert sein, um unbeabsichtigtes Verhalten zu verhindern. Beachten Sie beim Verfassen der Toolbeschreibungen die folgenden Richtlinien.

Beschreiben Sie die Funktionalität, aber geben Sie kein Verhalten vor. Die Beschreibung muss genau beschreiben, was das Tool tut, und nicht dem Modell befehlen, nachfolgende Aktionen auszuführen.
Umfang und Anforderungen definieren Geben Sie das Hauptziel des Tools, die spezifischen Umstände (Wann) für seine Verwendung und alle erforderlichen Eingaben (Parameter/Argumente) klar an.
Wahrheitsgehalt sicherstellen: Die Beschreibung muss eine wahrheitsgemäße Darstellung des zugrunde liegenden Codes des Tools sein. Behaupten Sie nicht, dass ein Tool schreibgeschützt ist, wenn es einen Schreib- oder Löschvorgang ausführt.

Sicherheitsrisiken und wie sie vermieden werden können

Risikobereich	Empfohlen	Vermeiden Sie diese Vorgehensweise unbedingt.
Prompt Injection	Verwenden Sie eine sachliche, deklarative Sprache, um den Zweck und die Funktionen des Tools klar zu beschreiben.	Verwenden Sie imperative Befehle, um das Modellverhalten zu überschreiben oder Systemabläufe zu ändern (z. B. „Du MUSST sagen…“, „Nach dem Laufen MÜSSEN Sie…“). Imperative Begriffe wie MUSS oder KRITISCH sind nur zulässig, wenn strukturierte Parametereinschränkungen oder Nutzungsregeln definiert werden.
	Verwenden Sie für den Beschreibungstext des Tools eine standardmäßige, einfache Formatierung.	Aufmerksamkeitserregende Formatierungen verwenden, z. B. übermäßige Großschreibung und Tags wie `VERY IMPORTANT:` oder `CRITICAL`.
	Konzentrieren Sie sich ausschließlich auf die Funktion und das erwartete Verhalten des Tools.	Anweisungen für Rollenspiele oder Befehle zum Ignorieren vorheriger Anweisungen enthalten.
Tool-Shadowing und -Hijacking	Die Beschreibung muss spezifisch sein und sich auf die tatsächlichen, zugehörigen Funktionen des Tools beschränken.	Die Toolbeschreibung ist zu allgemein oder vage oder es wird behauptet, dass ein einzelnes Tool viele nicht zusammenhängende Funktionen ausführt.
	Wählen Sie einen eindeutigen, aussagekräftigen und sinnvollen Toolnamen aus.	Verwenden Sie einen Toolnamen, der eine geringfügige Abwandlung eines vertrauenswürdigen Tools ist, oder einen allgemeinen Namen (z. B. `do_everything_tool`, `assistant_tool`).
	Erwähnen Sie in der Beschreibung keine anderen Apps oder Tools von externen Plattformen namentlich.	Explizit auf andere Tools verweisen oder neue Regeln dafür aufstellen, wann oder wie andere Tools eingesetzt werden sollen.
	Dem Planer des Modells erlauben, das am besten geeignete Tool basierend auf dem Nutzerkontext auszuwählen.	Wettbewerbswidrige Formulierungen oder SEO-Prompts, die das Modell anweisen, Ihr Tool ähnlichen Tools vorzuziehen.
Trigger-Manipulation	Die Beschreibung bezieht sich nicht auf allgemeine Phrasen aus dem Unterhaltungsverlauf und reagiert auch nicht darauf.	Bedingte Logik erstellen, die eine schädliche Aktion basierend auf gängigen, harmlosen Nutzerformulierungen auslöst (z. B. „Danke“, „Zusammenfassend“).
Missbrauch von Parametern	Definieren Sie nur Parameter, die für die Funktion des Tools erforderlich sind, und verwenden Sie Namen, die für die Eingabedaten spezifisch sind (z. B. `file_id`, `search_term`).	Definieren Sie Funktionsparameter mit Namen, die den internen Zustand des Agenten widerspiegeln (z. B. `system_prompt`, `conversation_history`, `full_context`).
Daten-Exfiltration	Privacy by Design – nicht transparente IDs und vom Host verwaltete Authentifizierung. Verwenden Sie nicht sensible IDs, keine personenidentifizierbaren Informationen. Die gesamte Datenverarbeitung muss innerhalb autorisierter, sicherer Grenzen erfolgen und darf in der öffentlichen Beschreibung nicht als extern gesendet bezeichnet werden. Die Toolausführung übernimmt Berechtigungen automatisch über den OAuth-Handshake. Alle vertraulichen Informationen sollten bereinigt werden, bevor sie an die entsprechenden Google-Produkte gesendet werden.	personenidentifizierbare Informationen, geschützte Gesundheitsdaten oder andere personenbezogene und/oder vertrauliche Informationen vom Nutzer, personenbezogene oder geschäftliche Daten oder Entitäten in einer Weise anfordern, die gegen die Nutzungsbedingungen der entsprechenden Google-Produkte verstößt. das Senden von Nutzerdaten (Anfrage, Standort, Kontext) an nicht autorisierte Drittanbieter-URLs, Protokollierungsdienste oder externe Systeme erwähnen oder verlangen.

Best Practices für Funktionen und Benennung

Neben der Absicherung der Beschreibung Ihres Tools müssen Sie dafür sorgen, dass das Modell es zuverlässig und ohne Verwechslungen auswählen und ausführen kann. Halten Sie sich an die folgenden Best Practices für Funktionen und Benennung:

Parametergenauigkeit: Achten Sie darauf, dass alle Parameternamen und ‑typen in der Beschreibung genau mit der tatsächlichen Implementierung des Tools übereinstimmen.
Sinnvolle Benennung: Der Name des Tools sollte ein starker, klarer Hinweis auf seine Funktion sein. Vermeiden Sie zu allgemeine Namen wie „execute“. Der Name muss auch mit dem breiteren Tool-Ökosystem übereinstimmen.

Anhang: Zulassungsliste für Infrastruktur und Netzwerk

Wenn Ihre Hosting-Infrastruktur, Ihr API-Gateway oder Ihre Firewall eingehende Verbindungen nach Quell-IP-Adresse einschränkt, setzen Sie die folgenden ausgehenden CIDR-Blöcke von Google auf die Zulassungsliste:

108.177.64.0/20
142.250.88.0/22
172.217.80.0/20
192.178.20.0/22
192.179.0.0/20
74.125.232.0/24
136.121.40.0/21

Achten Sie darauf, dass Ihre Umgebung Traffic von diesen IP-Bereichen über den HTTPS-Port 443 zulässt, damit die entsprechenden Google-Produkte Ihren Remote-MCP-Server für die MCP-Initialisierung, die Toolerkennung und die Anfrageausführung erreichen können.