Protocole de contexte des modèles (MCP)

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

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

• des outils qui effectuent des actions ;
• des ressources qui renvoient un contexte lisible ;
• des invites qui fournissent des modèles de messages réutilisables ; et
• des suggestions de complétion qui aident un client à renseigner les arguments d’une invite ou d’une ressource.

ADK-Rust est généralement le client MCP. McpToolset transforme les outils MCP découverts en valeurs Tool ADK-Rust ordinaires, afin qu’un LlmAgent puisse les sélectionner et les appeler. Le framework expose également les ressources, les invites, la complétion, les abonnements, la sollicitation d’informations et le cycle de vie négocié des tâches. Pour la création de serveurs MCP et les travaux avancés sur le protocole, ADK-Rust réexporte la version exacte de SDK rmcp qu’il utilise.

ADK-Rust 2 utilise rmcp 3.1, le SDK officiel de Rust. Le client annonce MCP 2025-11-25 et se connecte aux serveurs 2026-07-28 via leur procédure d’établissement de liaison historique. examples/mcp_protocol_revisions présente les deux révisions ainsi que l’extension de tâches SEP-2663 avec un serveur intégré.

Architecture

Rendering architecture…

Il existe deux couches distinctes :

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

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

Installation

La prise en charge de stdio local MCP est activée explicitement :

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

Ajoutez Streamable HTTP lors de la connexion à des services distants :

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

Les anciens rappels d’échantillonnage nécessitent la fonctionnalité distincte mcp-sampling. Le projet MCP a rendu obsolètes l’échantillonnage, les racines et la journalisation via SEP-2577 ; utilisez ces APIs uniquement pour maintenir 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 conserve les schémas d’entrée et de sortie du serveur tels quels. Chaque adaptateur de modèle normalise une copie pour son fournisseur lors de la construction de la requête du modèle. Cela permet au même serveur MCP de fonctionner avec Gemini, OpenAI, Anthropic et d’autres fournisseurs sans altérer 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 pratiques renvoient une liste vide lorsqu’un serveur plus ancien n’implémente pas la liste des ressources ou des invites. Les opérations portant 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’un ensemble de processus enfants locaux MCP plutôt que d’une seule connexion statique.

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 avec {server_id}__{tool_name}. Les noms uniques restent inchangés.

Le moniteur d’intégrité détecte une connexion MCP fermée. Un RestartPolicy configuré contrôle les tentatives limitées avec une temporisation exponentielle. Il s’agit d’une supervision de connexion, et non d’une vérification d’intégrité au niveau de l’application : utilisez un outil de domaine ou une sonde de service distincte lorsque vous devez vérifier la base de données sous-jacente du serveur ou un 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 met à l’épreuve 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 diffusé à distance

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 générateur applique des délais d’expiration aux requêtes, des en-têtes personnalisés, des jetons bearer, 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 à identifiants client fixe OAuth 2.0. Il est utile pour un serveur possédant un point de terminaison de jeton connu. Il ne s’agit pas du flux d’autorisation MCP complet : il n’effectue pas la découverte des métadonnées de la ressource protégée, la découverte du serveur d’autorisation, l’autorisation via navigateur, PKCE ou la négociation d’indicateur de ressource. Utilisez l’autorisation APIs de rmcp ou un composant d’identité externe lorsque le déploiement requiert ce flux.

Sollicitation

Un serveur MCP peut avoir besoin d’informations qui n’étaient pas incluses dans les arguments de l’outil. Dans ce cas, il peut renvoyer une demande de sollicitation au client. L’application décide comment présenter la demande à une personne et s’il convient de l’accepter, de la refuser ou de l’annuler.

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

ADK-Rust annonce à la fois l’interface et l’URL. Une erreur ou une panique du gestionnaire est convertie 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 ayant des conséquences.

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

Tâches MCP de longue durée

MCP 2025-11-25 peut convertir un appel d’outil en tâche de protocole. ADK-Rust utilise le flux de tâche uniquement lorsque le serveur a négocié tasks.requests.tools.call et que l’outil déclare la prise en charge obligatoire ou facultative des tâches.

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

En mode tâche, ADK-Rust :

1. envoie tools/call avec les métadonnées officielles de la tâche ;
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 ou sa limite d’interrogations locale est atteinte.

input_required est renvoyée sous forme d’erreur typée, car un appel d’outil ADK ordinaire ne dispose pas encore d’un canal de reprise neutre vis-à-vis du protocole permettant de fournir cette entrée manquante. Concevez explicitement cette interaction dans le flux de travail qui en est responsable.

Carte 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, une autre équipe, un autre langage, une autre limite de sécurité ou un autre déploiement possède la capacité et doit publier son propre contrat.

Pour les déploiements en production :

• exposez le plus petit ensemble d’outils utile ;
• séparez les actions en lecture seule des actions ayant des conséquences ;
• gardez les secrets hors des arguments de ligne de commande et des fichiers mcp.json versionnés ;
• authentifiez les serveurs HTTP distants et limitez strictement les identifiants ;
• considérez les descriptions des outils et le contenu renvoyé par les serveurs comme des entrées non fiables ;
• maintenez l’autorisation et l’approbation ADK-Rust autour de l’exécution des outils ;
• imposez des délais d’expiration aux connexions, aux outils et aux tâches ; et
• consignez les appels d’outils, les approbations, les erreurs et les changements du cycle de vie des serveurs.

Limites actuelles

• McpServerManager gère les processus enfants locaux via stdio. Les services HTTP distants utilisent McpHttpClientBuilder et une configuration gérée par l’application.
• Les vérifications d’état du gestionnaire détectent les connexions MCP fermées ; elles n’appellent pas d’outil d’état au niveau métier.
• Les modifications du registre sont sérialisées pendant qu’un processus enfant termine sa négociation MCP.
• autoApprove concerne la compatibilité de configuration, et non l’application des autorisations.
• L’assistant OAuth intégré correspond aux identifiants du client, et non au flux complet de découverte et d’autorisation de l’utilisateur MCP OAuth.

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 officielle (rmcp)
• Documentation de rmcp 3.1 API
• Normalisation des schémas tenant compte du fournisseur