Protocole de Contexte de Modèle (MCP)

Plan de la documentation : Vue d'ensemble et architecture · Client · Gestionnaire dynamique · Création de serveurs · Sécurité · Tests

MCP offre à une application d'IA un moyen standard de découvrir et d'utiliser les capacités détenues par un autre processus ou service. Un serveur peut publier :

• tools qui effectuent des actions ;
• resources qui retournent un contexte lisible ;
• prompts qui fournissent des modèles de messages réutilisables ; et
• completion suggestions qui aident un client à remplir les arguments de prompt ou de resource.

ADK-Rust est généralement le client MCP. McpToolset transforme les tools MCP découverts en valeurs normales ADK-Rust Tool, de sorte qu'un LlmAgent puisse les sélectionner et les appeler. Le framework expose également les resources, les prompts, la completion, les abonnements, l'élicitation et le cycle de vie négocié des tâches. Pour la création de serveurs MCP et les travaux de protocole avancés, ADK-Rust ré-exporte la version exacte du SDK rmcp qu'il utilise.

ADK-Rust 2 utilise actuellement rmcp 2.2, le Rust SDK officiel aligné sur la spécification MCP 2025-11-25.

Architecture

Rendering architecture…

Il y a deux couches distinctes :

1. McpToolset possède une connexion client MCP initialisée. Il découvre les capacités du serveur et les adapte à ADK-Rust.
2. McpServerManager possède un registre évolutif de serveurs stdio locaux. Il démarre, surveille, redémarre, met à jour, active, désactive, persiste et agrège ces connexions.

Le gestionnaire n'accorde pas l'approbation des outils. Il préserve autoApprove lors de la lecture d'une configuration compatible, mais l'application doit appliquer sa politique normale d'autorisation et d'approbation ADK-Rust.

Installation

Le support local stdio MCP est optionnel :

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

Ajoutez le HTTP streamable lors de la connexion à des services distants :

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

Les rappels d'échantillonnage hérités nécessitent la fonctionnalité mcp-sampling distincte. Le projet MCP a déprécié l'échantillonnage, les racines et la journalisation via SEP-2577 ; utilisez ces API uniquement lors du maintien d'un déploiement compatible.

Connecter un serveur local

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 maintient les schémas d'entrée et de sortie du serveur intacts. Chaque adaptateur de modèle normalise une copie pour son fournisseur lorsqu'il construit la requête de modèle. Cela permet au même serveur MCP de fonctionner avec Gemini, OpenAI, Anthropic et d'autres fournisseurs sans endommager le schéma source.

Utiliser le protocole au-delà des outils

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?;

Les méthodes de commodité renvoient une liste vide lorsqu'un serveur plus ancien n'implémente pas la liste des ressources ou des invites. Les opérations sur une ressource ou une invite déclarée renvoient une erreur lorsque l'appel distant échoue.

Gestion dynamique des serveurs

Utilisez McpServerManager lorsque l'application a besoin d'une flotte de processus enfants MCP locaux plutôt que d'une connexion statique unique.

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()?;

Le registre d'exécution prend en charge :

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?;

Lorsque deux serveurs publient le même nom d'outil, l'ensemble d'outils agrégé préfixe les deux noms comme {server_id}__{tool_name}. Les noms uniques restent inchangés.

Le moniteur de santé détecte une connexion MCP fermée. Une RestartPolicy configurée contrôle les tentatives limitées avec un backoff exponentiel. Il s'agit d'une supervision de connexion, pas d'une vérification de santé au niveau de l'application : utilisez un outil de domaine ou une sonde de service séparée lorsque vous devez vérifier la base de données de support du serveur ou une API externe.

Exécutez l'exemple déterministe :

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

Il démarre un véritable serveur enfant Rust MCP et exerce la découverte, un appel d'outil, l'ajout/l'activation/la mise à jour/la désactivation/la suppression à l'exécution, la persistance de la configuration et l'arrêt. Il ne télécharge pas de paquets et ne nécessite pas de clé API.

HTTP distant et streamable

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?;

Le constructeur applique des délais d'attente de requête, des en-têtes personnalisés, des jetons d'authentification (bearer tokens), des en-têtes de clé API personnalisés et une récupération limitée lorsqu'une session HTTP expire.

OAuth2Config implémente une requête de jeton client-credentials OAuth 2.0 fixe. Il est utile pour un serveur avec un token endpoint connu. Ce n'est pas le flux d'autorisation MCP complet : il n'effectue pas la découverte de métadonnées de ressource protégée, la découverte de serveur d'autorisation, l'autorisation de navigateur, le PKCE, ou la négociation d'indicateur de ressource. Utilisez les APIs d'autorisation de rmcp ou un composant d'identité externe lorsque le déploiement requiert ce flux.

Élicitation

Un serveur MCP peut avoir besoin d'informations que les arguments de l'outil n'incluaient pas. Dans ce cas, il peut envoyer une requête d'élicitation au client. L'application décide comment afficher la requête à une personne et si elle doit l'accepter, la refuser ou l'annuler.

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

ADK-Rust propose la sollicitation de formulaires et d'URL. Une erreur de gestionnaire ou un panic est converti en refus afin que la connexion MCP reste utilisable. Validez les valeurs renvoyées et appliquez les règles de consentement dans l'application avant d'accepter une requête consécutive.

Consultez examples/mcp_elicitation pour un serveur complet et un client interactif.

Tâches MCP de longue durée

MCP 2025-11-25 peut déplacer un appel d'outil vers une tâche de protocole. ADK-Rust utilise le flux de tâches uniquement lorsque le serveur a négocié tasks.requests.tools.call et que l'outil déclare un support de tâche requis ou optionnel.

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),
);

Pour le mode tâche, ADK-Rust :

1. envoie tools/call avec les métadonnées de tâche officielles ;
2. reçoit la tâche créée ;
3. interroge tasks/get en utilisant l'intervalle suggéré par le serveur ;
4. lit la charge utile finale via tasks/result ; et
5. appelle tasks/cancel lorsque son délai d'attente local ou sa limite d'interrogation est atteint.

input_required est renvoyé comme une erreur typée car un appel d'outil ADK ordinaire n'a pas encore de canal de reprise neutre au niveau du protocole pour fournir cette entrée manquante. Concevez cette interaction explicitement dans le flux de travail propriétaire.

Mappage des capacités

Choisir la limite

Utilisez un FunctionTool Rust lorsque la capacité appartient au même processus et à la même version. Utilisez MCP lorsqu'un autre programme, équipe, langage, limite de sécurité ou déploiement possède la capacité et doit publier son propre contrat.

Pour les déploiements en production :

• exposer l'ensemble d'outils utiles le plus restreint ;
• séparer les actions en lecture seule et les actions à conséquences ;
• garder les secrets hors des arguments de ligne de commande et des fichiers mcp.json validés ;
• authentifier les serveurs HTTP distants et limiter strictement la portée des identifiants ;
• traiter les descriptions d'outils et le contenu retourné par le serveur comme des entrées non fiables ;
• maintenir l'autorisation et l'approbation ADK-Rust autour de l'exécution d'outils ;
• limiter les délais de connexion, d'outil et de tâche ; et
• enregistrer les appels d'outils, les approbations, les erreurs et les changements de cycle de vie du serveur.

Limites actuelles

• McpServerManager gère les processus enfants stdio locaux. Les services HTTP distants utilisent McpHttpClientBuilder et une configuration appartenant à l'application.
• Les vérifications de santé du gestionnaire détectent les connexions MCP fermées ; elles n'appellent pas un outil de santé de niveau métier.
• Les mutations de registre sont sérialisées pendant qu'un enfant complète son handshake MCP.
• autoApprove est la compatibilité de configuration, et non l'application de l'autorisation.
• L'aide OAuth intégrée est des identifiants de client, et non le flux complet de découverte OAuth MCP et d'autorisation utilisateur.

Ces limites sont énoncées afin que les décisions de déploiement restent explicites.

Références

• Spécification MCP 2025-11-25
• SDK Rust Officiel (rmcp)
• Documentation de l'API rmcp 2.2
• Normalisation du schéma sensible au fournisseur