Protocolo de contexto del modelo (MCP)

Mapa de documentación: Descripción general y arquitectura · Cliente · Administrador dinámico · Creación de servidores · Seguridad · Pruebas

MCP proporciona a una aplicación de IA una forma estándar de descubrir y usar capacidades propiedad de otro proceso o servicio. Un servidor puede publicar:

• herramientas que realizan acciones;
• recursos que devuelven contexto legible;
• indicaciones que proporcionan plantillas de mensajes reutilizables; y
• sugerencias de completado que ayudan a un cliente a rellenar argumentos de indicaciones o recursos.

ADK-Rust suele ser el cliente MCP. McpToolset convierte las herramientas MCP descubiertas en valores normales ADK-Rust Tool, de modo que un LlmAgent puede seleccionarlas y llamarlas. El marco también expone recursos, indicaciones, completado, suscripciones, elicitación y el ciclo de vida de tareas negociado. Para la creación de servidores MCP y el trabajo avanzado con el protocolo, ADK-Rust vuelve a exportar la versión exacta de rmcp SDK que utiliza.

ADK-Rust 2 usa rmcp 3.1, el SDK oficial de Rust. El cliente anuncia MCP 2025-11-25 y se conecta a servidores 2026-07-28 mediante su protocolo de enlace heredado. examples/mcp_protocol_revisions demuestra ambas revisiones y la extensión de tareas SEP-2663 contra un servidor incluido.

Arquitectura

Rendering architecture…

Hay dos capas independientes:

1. McpToolset posee una conexión de cliente MCP inicializada. Descubre las capacidades del servidor y las adapta a ADK-Rust.
2. McpServerManager posee un registro cambiante de servidores stdio locales. Inicia, supervisa, reinicia, actualiza, habilita, deshabilita, persiste y agrega esas conexiones.

El administrador no concede la aprobación de herramientas. Conserva autoApprove al leer configuraciones compatibles, pero la aplicación debe aplicar su política normal de autorización y aprobación de ADK-Rust.

Instalar

La compatibilidad con MCP stdio local es opcional:

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

Añade Streamable HTTP al conectarte a servicios remotos:

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

Las devoluciones de llamada de muestreo heredadas requieren la característica independiente mcp-sampling. El proyecto MCP ha dejado obsoletos el muestreo, las raíces y el registro mediante SEP-2577; usa esos APIs solo cuando mantengas una implementación compatible.

Conectar un servidor 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 mantiene intactos los esquemas de entrada y salida del servidor. Cada adaptador de modelo normaliza una copia para su proveedor al construir la solicitud del modelo. Esto permite que el mismo servidor MCP funcione con Gemini, OpenAI, Anthropic y otros proveedores sin dañar el esquema de origen.

Usar el protocolo más allá de las herramientas

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

Los métodos de conveniencia devuelven una lista vacía cuando un servidor antiguo no implementa el listado de recursos o indicaciones. Las operaciones sobre un recurso o indicación declarados devuelven un error cuando falla la llamada remota.

Gestión dinámica de servidores

Usa McpServerManager cuando la aplicación necesite un conjunto de procesos secundarios locales MCP en lugar de una única conexión estática.

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

El registro del tiempo de ejecución admite:

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

Cuando dos servidores publican el mismo nombre de herramienta, el conjunto de herramientas agregado antepone a ambos nombres el prefijo {server_id}__{tool_name}. Los nombres únicos no cambian.

El monitor de estado detecta una conexión MCP cerrada. Un RestartPolicy configurado controla los reintentos limitados con retroceso exponencial. Esta es una supervisión de la conexión, no una comprobación del estado a nivel de aplicación: use una herramienta de dominio o una sonda de servicio independiente cuando necesite verificar la base de datos de respaldo del servidor u otro API externo.

Ejecute el ejemplo determinista:

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

Inicia un servidor hijo real de Rust MCP y prueba el descubrimiento, una llamada a una herramienta, la adición, habilitación, actualización, deshabilitación y eliminación en tiempo de ejecución, la persistencia de la configuración y el apagado. No descarga paquetes ni requiere una clave API.

HTTP remoto transmitible

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

El constructor aplica tiempos de espera de solicitudes, encabezados personalizados, tokens de portador, encabezados de clave API personalizados y recuperación limitada cuando una sesión HTTP caduca.

OAuth2Config implementa una solicitud de token de credenciales de cliente fija de OAuth 2.0. Es útil para un servidor con un punto de conexión de tokens conocido. No constituye el flujo de autorización MCP completo: no realiza el descubrimiento de metadatos del recurso protegido, el descubrimiento del servidor de autorización, la autorización mediante navegador, PKCE ni la negociación de indicadores de recursos. Use la APIs de autorización de rmcp o un componente de identidad externo cuando la implementación requiera ese flujo.

Solicitud de información

Un servidor MCP puede necesitar información que no se incluyó en los argumentos de la herramienta. En ese caso, puede enviar una solicitud de solicitud de información de vuelta al cliente. La aplicación decide cómo mostrar la solicitud a una persona y si aceptarla, rechazarla o cancelarla.

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

ADK-Rust anuncia tanto formularios como la obtención de URL. Un error o pánico del controlador se convierte en una denegación para que la conexión MCP siga siendo utilizable. Valide los valores devueltos y aplique las reglas de consentimiento en la aplicación antes de aceptar una solicitud con consecuencias.

Consulte examples/mcp_elicitation para ver un servidor completo y un cliente interactivo.

Tareas de MCP de larga duración

MCP 2025-11-25 puede convertir una llamada a una herramienta en una tarea de protocolo. ADK-Rust utiliza el flujo de tareas únicamente cuando el servidor ha negociado tasks.requests.tools.call y la herramienta declara compatibilidad con tareas obligatorias u opcionales.

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

Para el modo de tareas, ADK-Rust:

1. envía tools/call con los metadatos oficiales de la tarea;
2. recibe la tarea creada;
3. consulta tasks/get utilizando el intervalo sugerido por el servidor;
4. lee la carga útil final mediante tasks/result; y
5. llama a tasks/cancel cuando se alcanza su tiempo de espera local o el límite de consultas.

input_required se devuelve como un error tipado porque una llamada ordinaria a la herramienta ADK aún no dispone de un canal de reanudación neutral respecto al protocolo para proporcionar esa entrada faltante. Diseñe explícitamente esa interacción en el flujo de trabajo responsable.

Mapa de capacidades

Elección del límite

Usa un FunctionTool de Rust cuando la capacidad pertenezca al mismo proceso y versión. Usa MCP cuando otro programa, equipo, lenguaje, límite de seguridad o implementación sea responsable de la capacidad y deba publicar su propio contrato.

Para implementaciones en producción:

• expón el conjunto mínimo de herramientas útil;
• separa las acciones de solo lectura de las acciones con consecuencias;
• mantén los secretos fuera de los argumentos de la línea de comandos y de los archivos mcp.json confirmados;
• autentica los servidores HTTP remotos y limita estrictamente el alcance de las credenciales;
• trata las descripciones de las herramientas y el contenido devuelto por el servidor como entradas no confiables;
• conserva la autorización y aprobación de ADK-Rust en torno a la ejecución de herramientas;
• establece límites para los tiempos de espera de conexión, herramientas y tareas; y
• registra las llamadas a herramientas, las aprobaciones, los errores y los cambios en el ciclo de vida del servidor.

Límites actuales

• McpServerManager administra procesos secundarios locales de stdio. Los servicios remotos HTTP usan McpHttpClientBuilder y configuración propiedad de la aplicación.
• Las comprobaciones de estado del administrador detectan conexiones MCP cerradas; no llaman a una herramienta de estado de nivel empresarial.
• Las mutaciones del registro se serializan mientras un proceso secundario completa su protocolo de enlace MCP.
• autoApprove corresponde a la compatibilidad de configuración, no a la aplicación de la autorización.
• El asistente OAuth integrado proporciona credenciales de cliente, no el flujo completo de descubrimiento y autorización de usuario de MCP OAuth.

Estos límites se indican para que las decisiones de implementación sigan siendo explícitas.

Referencias

• Especificación de MCP 2025-11-25
• SDK oficial de Rust (rmcp)
• Documentación de rmcp 3.1 API
• Normalización de esquemas consciente del proveedor