Model Context Protocol (MCP)

Dokumentationsübersicht: Übersicht und Architektur · Client · Dynamischer Manager · Servererstellung · Sicherheit · Tests

MCP bietet einer KI-Anwendung eine standardisierte Möglichkeit, Funktionen zu entdecken und zu nutzen, die einem anderen Prozess oder Dienst gehören. Ein Server kann Folgendes veröffentlichen:

• Tools, die Aktionen ausführen;
• Ressourcen, die lesbaren Kontext zurückgeben;
• Prompts, die wiederverwendbare Nachrichtenvorlagen bereitstellen; und
• Vervollständigungsvorschläge, die einem Client dabei helfen, Prompt- oder Ressourcenargumente auszufüllen.

ADK-Rust ist normalerweise der MCP Client. McpToolset wandelt entdeckte MCP-Tools in gewöhnliche ADK-Rust-Tool-Werte um, sodass ein LlmAgent sie auswählen und aufrufen kann. Das Framework stellt außerdem Ressourcen, Prompts, Vervollständigung, Abonnements, Abfragen und den ausgehandelten Aufgabenlebenszyklus bereit. Für die MCP-Servererstellung und fortgeschrittene Protokollarbeit exportiert ADK-Rust die exakt verwendete rmcp-SDK-Version erneut.

ADK-Rust 2 verwendet rmcp 3.1, das offizielle Rust-SDK. Der Client kündigt MCP 2025-11-25 an und verbindet sich über den älteren Handshake mit 2026-07-28-Servern. examples/mcp_protocol_revisions demonstriert beide Revisionen sowie die SEP-2663-Aufgabenerweiterung mit einem gebündelten Server.

Architektur

Rendering architecture…

Es gibt zwei getrennte Ebenen:

1. McpToolset verwaltet eine einzige initialisierte MCP-Clientverbindung. Sie entdeckt die Funktionen des Servers und passt sie an ADK-Rust an.
2. McpServerManager verwaltet eine sich ändernde Registry lokaler stdio-Server. Sie startet, überwacht, startet neu, aktualisiert, aktiviert, deaktiviert, speichert und aggregiert diese Verbindungen.

Der Manager erteilt keine Tool-Genehmigung. Er bewahrt autoApprove beim Lesen kompatibler Konfigurationen, aber die Anwendung muss ihre normale ADK-Rust-Autorisierungs- und Genehmigungsrichtlinie anwenden.

Installation

Die lokale stdio-Unterstützung für MCP ist optional:

[dependencies]
adk-tool = { version = "2.1.0", features = ["mcp"] }

Füge Streamable HTTP hinzu, wenn eine Verbindung zu entfernten Diensten hergestellt wird:

adk-tool = { version = "2.1.0", features = ["mcp", "http-transport"] }

Legacy-Sampling-Callbacks erfordern das separate Feature mcp-sampling. Das Projekt MCP hat Sampling, Roots und Logging über SEP-2577 veraltet; verwende diese APIs nur bei der Wartung einer kompatiblen Bereitstellung.

Einen lokalen Server verbinden

use adk_tool::{
    McpToolset,
    mcp::rmcp::{ServiceExt, transport::TokioChildProcess},
};
use std::sync::Arc;
use tokio::process::Command;

let command = Command::new("./target/release/company-mcp");
let client = ().serve(TokioChildProcess::new(command)?).await?;

let toolset = McpToolset::new(client)
    .with_name("company_tools")
    .with_tools(&["find_customer", "read_order", "request_refund"]);

let agent = LlmAgentBuilder::new("support")
    .model(model)
    .toolset(Arc::new(toolset.clone()))
    .build()?;

// Keep the token when the application owns the process lifecycle.
let shutdown = toolset.cancellation_token().await;
// ... run the agent ...
shutdown.cancel();

McpToolset bewahrt die Eingabe- und Ausgabeschemas des Servers unverändert. Jeder Modelladapter normalisiert eine Kopie für seinen Anbieter, wenn er die Modellanfrage erstellt. Dadurch kann derselbe MCP-Server mit Gemini, OpenAI, Anthropic und anderen Anbietern arbeiten, ohne das Quellschema zu beschädigen.

Das Protokoll über Tools hinaus verwenden

use serde_json::json;

let resources = toolset.list_resources().await?;
let templates = toolset.list_resource_templates().await?;
let contents = toolset.read_resource("company://policy/refunds").await?;

let prompts = toolset.list_prompts().await?;
let prompt = toolset
    .get_prompt(
        "investigate_order",
        Some(serde_json::Map::from_iter([
            ("order_id".to_string(), json!("ORD-1042")),
        ])),
    )
    .await?;

let suggestions = toolset
    .complete_prompt_argument("investigate_order", "order_id", "ORD-", None)
    .await?;

toolset.subscribe_resource("company://inventory/sku-42").await?;
// ... receive notifications in a custom ClientHandler ...
toolset.unsubscribe_resource("company://inventory/sku-42").await?;

Die Komfortmethoden geben eine leere Liste zurück, wenn ein älterer Server das Auflisten von Ressourcen oder Prompts nicht implementiert. Operationen für eine deklarierte Ressource oder einen Prompt geben einen Fehler zurück, wenn der Remote-Aufruf fehlschlägt.

Dynamische Serververwaltung

Verwende McpServerManager, wenn die Anwendung eine Gruppe lokaler MCP- Kindprozesse statt einer einzigen statischen Verbindung benötigt.

use adk_tool::mcp::manager::{McpServerConfig, McpServerManager};
use std::collections::HashMap;
use std::sync::Arc;
use std::time::Duration;

let manager = Arc::new(McpServerManager::from_json_file("mcp.json")?
    .with_name("product_mcp_servers")
    .with_health_check_interval(Duration::from_secs(15))
    .with_grace_period(Duration::from_secs(2)));

let outcomes = manager.start_all().await;
for (server_id, outcome) in outcomes {
    if let Err(error) = outcome {
        eprintln!("{server_id} did not start: {error}");
    }
}
manager.start_monitoring();

let agent = LlmAgentBuilder::new("operator")
    .model(model)
    .toolset(manager.clone())
    .build()?;

Die Laufzeitregistrierung unterstützt:

manager.add_server("billing".into(), billing_config).await?;
manager.start_server("billing").await?;

manager.update_server("billing", replacement_config).await?;
manager.disable_server("billing").await?;
manager.enable_server("billing").await?;

manager.save_json_file("mcp.json").await?;
manager.remove_server("billing").await?;
manager.shutdown().await?;

Wenn zwei Server denselben Toolnamen veröffentlichen, versieht das aggregierte Toolset beide Namen mit dem Präfix {server_id}__{tool_name}. Eindeutige Namen bleiben unverändert.

Der Gesundheitsmonitor erkennt eine geschlossene MCP-Verbindung. Ein konfiguriertes RestartPolicy steuert begrenzte Wiederholungsversuche mit exponentiellem Backoff. Dies ist eine Verbindungsüberwachung, keine anwendungsebene Gesundheitsprüfung: Verwenden Sie ein Domänenwerkzeug oder eine separate Dienstprüfung, wenn Sie die zugrunde liegende Datenbank des Servers oder ein externes API überprüfen müssen.

Führen Sie das deterministische Beispiel aus:

cargo run --manifest-path examples/mcp_manager/Cargo.toml

Es startet einen echten untergeordneten Rust-MCP-Server und testet Discovery, einen Tool-Aufruf, Laufzeit-Hinzufügen/Aktivieren/Aktualisieren/Deaktivieren/Entfernen, die Persistenz der Konfiguration und das Herunterfahren. Es lädt keine Pakete herunter und erfordert keinen API-Schlüssel.

Remote Streamable HTTP

use adk_tool::{McpAuth, McpHttpClientBuilder};
use std::time::Duration;

let toolset = McpHttpClientBuilder::new("https://mcp.example.com/mcp")
    .with_auth(McpAuth::bearer(std::env::var("MCP_TOKEN")?))
    .header("X-Tenant-ID", "tenant-42")
    .timeout(Duration::from_secs(30))
    .reinit_on_expired_session(true)
    .connect()
    .await?;

Der Builder wendet Anfrage-Timeouts, benutzerdefinierte Header, Bearer-Token, benutzerdefinierte API-Schlüssel-Header und eine begrenzte Wiederherstellung an, wenn eine HTTP-Sitzung abläuft.

OAuth2Config implementiert eine festgelegte OAuth-2.0-Token-Anfrage mit Client-Anmeldedaten. Dies ist für einen Server mit einem bekannten Token-Endpunkt nützlich. Es handelt sich nicht um den vollständigen MCP-Autorisierungsablauf: Die Erkennung von Metadaten geschützter Ressourcen, die Erkennung des Autorisierungsservers, die Browser-Autorisierung, PKCE oder die Aushandlung von Ressourcenindikatoren werden nicht durchgeführt. Verwenden Sie die Autorisierung APIs von rmcp oder eine externe Identitätskomponente, wenn die Bereitstellung diesen Ablauf erfordert.

Anforderung zusätzlicher Informationen

Ein MCP-Server benötigt möglicherweise Informationen, die in den Tool-Argumenten nicht enthalten waren. In diesem Fall kann er eine Anforderung zusätzlicher Informationen an den Client zurücksenden. Die Anwendung entscheidet, wie die Anfrage einer Person angezeigt wird und ob sie akzeptiert, abgelehnt oder abgebrochen wird.

let toolset = McpToolset::with_elicitation_handler(
    transport,
    Arc::new(MyElicitationHandler),
).await?;

ADK-Rust unterstützt sowohl Formulare als auch die Erfassung durch URL. Ein Fehler oder Panic in einem Handler wird in eine Ablehnung umgewandelt, damit die MCP-Verbindung weiterhin verwendbar bleibt. Validieren Sie die zurückgegebenen Werte und wenden Sie vor der Annahme einer folgenreichen Anfrage die Einwilligungsregeln in der Anwendung an.

Siehe examples/mcp_elicitation für einen vollständigen Server und interaktiven Client.

Lang laufende MCP-Aufgaben

MCP 2025-11-25 kann einen Tool-Aufruf in eine Protokollaufgabe umwandeln. ADK-Rust verwendet den Aufgabenablauf nur, wenn der Server tasks.requests.tools.call ausgehandelt hat und das Tool erforderliche oder optionale Aufgabenunterstützung deklariert.

use adk_tool::McpTaskConfig;
use std::time::Duration;

let toolset = McpToolset::new(client).with_task_support(
    McpTaskConfig::enabled()
        .poll_interval(Duration::from_secs(1))
        .timeout(Duration::from_secs(120))
        .max_attempts(120),
);

Im Aufgabenmodus führt ADK-Rust folgende Schritte aus:

1. sendet tools/call mit offiziellen Aufgabenmetadaten;
2. empfängt die erstellte Aufgabe;
3. fragt tasks/get unter Verwendung des vom Server empfohlenen Intervalls ab;
4. liest die endgültige Nutzlast über tasks/result; und
5. ruft tasks/cancel auf, wenn das lokale Zeitlimit oder die Abfragebegrenzung erreicht ist.

input_required wird als typisierter Fehler zurückgegeben, da ein gewöhnlicher ADK-Tool-Aufruf noch keinen protokollneutralen Fortsetzungskanal zum Übermitteln dieser fehlenden Eingabe besitzt. Entwerfen Sie diese Interaktion ausdrücklich im zuständigen Workflow.

Fähigkeitsübersicht

Die Grenze wählen

Verwenden Sie ein Rust-FunctionTool, wenn die Fähigkeit zum selben Prozess und Release gehört. Verwenden Sie MCP, wenn ein anderes Programm, Team, eine andere Sprache, Sicherheitsgrenze oder Bereitstellung für die Fähigkeit verantwortlich ist und ihren eigenen Vertrag veröffentlichen sollte.

Für Produktionsbereitstellungen:

• stellen Sie den kleinstmöglichen nützlichen Werkzeugsatz bereit;
• trennen Sie schreibgeschützte und folgenreiche Aktionen;
• halten Sie Geheimnisse aus Befehlszeilenargumenten und versionierten mcp.json-Dateien heraus;
• authentifizieren Sie entfernte HTTP-Server und beschränken Sie Anmeldeinformationen auf den erforderlichen Umfang;
• behandeln Sie Werkzeugbeschreibungen und von Servern zurückgegebene Inhalte als nicht vertrauenswürdige Eingaben;
• behalten Sie ADK-Rust-Autorisierung und -Genehmigung rund um die Werkzeugausführung bei;
• begrenzen Sie Verbindungs-, Werkzeug- und Aufgaben-Timeouts; und
• protokollieren Sie Werkzeugaufrufe, Genehmigungen, Fehler und Änderungen am Serverlebenszyklus.

Aktuelle Einschränkungen

• McpServerManager verwaltet lokale Stdio-Kinderprozesse. Für entfernte HTTP-Dienste werden McpHttpClientBuilder und anwendungseigene Konfiguration verwendet.
• Zustandsprüfungen des Managers erkennen geschlossene MCP-Verbindungen; sie rufen kein geschäftliches Zustandsprüfungswerkzeug auf.
• Änderungen an der Registry werden serialisiert, während ein Kind seinen MCP-Handshake abschließt.
• autoApprove betrifft die Konfigurationskompatibilität, nicht die Durchsetzung der Autorisierung.
• Der integrierte OAuth-Helfer dient der Client-Authentifizierung, nicht dem vollständigen MCP-OAuth- Erkennungs- und Benutzerautorisierungsablauf.

Diese Einschränkungen werden genannt, damit Bereitstellungsentscheidungen ausdrücklich bleiben.

Referenzen

• MCP-Spezifikation 2025-11-25
• Offizielles Rust-SDK (rmcp)
• rmcp 3.1-API-Dokumentation
• Anbieterbewusste Schemanormalisierung