Protocolo de Contexto de Modelo (MCP)

Mapa da documentação: Visão geral e arquitetura · Cliente · Gerenciador dinâmico · Autoria de servidor · Segurança · Testes

MCP oferece a uma aplicação de IA uma maneira padrão de descobrir e usar recursos pertencentes a outro processo ou serviço. Um servidor pode publicar:

• ferramentas que executam ações;
• recursos que retornam contexto legível;
• prompts que fornecem modelos de mensagens reutilizáveis; e
• sugestões de complemento que ajudam um cliente a preencher argumentos de prompt ou recurso.

ADK-Rust geralmente é o cliente MCP. McpToolset transforma as ferramentas MCP descobertas em valores normais ADK-Rust Tool, para que um LlmAgent possa selecioná-las e chamá-las. A estrutura também expõe recursos, prompts, complemento, assinaturas, elicitação e o ciclo de vida de tarefas negociado. Para autoria de servidor MCP e trabalho avançado com o protocolo, ADK-Rust reexporta a versão exata SDK de rmcp que utiliza.

ADK-Rust 2 usa rmcp 3.1, o SDK oficial do Rust. O cliente anuncia MCP 2025-11-25 e se conecta a servidores 2026-07-28 por meio do handshake legado. examples/mcp_protocol_revisions demonstra ambas as revisões e a extensão de tarefas SEP-2663 em relação a um servidor integrado.

Arquitetura

Rendering architecture…

Há duas camadas separadas:

1. McpToolset é responsável por uma conexão de cliente MCP inicializada. Ele descobre os recursos do servidor e os adapta a ADK-Rust.
2. McpServerManager é responsável por um registro mutável de servidores stdio locais. Ele inicia, monitora, reinicia, atualiza, habilita, desabilita, persiste e agrega essas conexões.

O gerenciador não concede aprovação de ferramentas. Ele preserva autoApprove ao ler configurações compatíveis, mas o aplicativo deve aplicar sua política normal de autorização e aprovação ADK-Rust.

Instalação

O suporte a stdio local MCP é opcional:

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

Adicione Streamable HTTP ao conectar-se a serviços remotos:

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

Os callbacks de amostragem legados exigem o recurso separado mcp-sampling. O projeto MCP descontinuou a amostragem, as raízes e o registro por meio do SEP-2577; use esses APIs somente ao manter uma implantação compatível.

Conectar um 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 mantém os esquemas de entrada e saída do servidor intactos. Cada adaptador de modelo normaliza uma cópia para seu provedor ao construir a solicitação do modelo. Isso permite que o mesmo servidor MCP funcione com Gemini, OpenAI, Anthropic e outros provedores sem danificar o esquema de origem.

Usar o protocolo além das ferramentas

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

Os métodos de conveniência retornam uma lista vazia quando um servidor mais antigo não implementa a listagem de recursos ou prompts. As operações em um recurso ou prompt declarado retornam um erro quando a chamada remota falha.

Gerenciamento dinâmico de servidores

Use McpServerManager quando o aplicativo precisar de uma frota de processos filho MCP locais em vez de uma única conexão 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()?;

O registro de tempo de execução oferece suporte a:

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

Quando dois servidores publicam o mesmo nome de ferramenta, o conjunto agregado de ferramentas adiciona o prefixo {server_id}__{tool_name} a ambos os nomes. Nomes exclusivos permanecem inalterados.

O monitor de integridade detecta uma conexão MCP fechada. Um RestartPolicy configurado controla novas tentativas limitadas com espera exponencial. Isso é supervisão da conexão, não uma verificação de integridade no nível da aplicação: use uma ferramenta de domínio ou uma sonda de serviço se precisar verificar o banco de dados de suporte do servidor ou um API externo.

Execute o exemplo determinístico:

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

Ele inicia um servidor filho real em Rust MCP e exercita descoberta, uma chamada de ferramenta, adição/ativação/atualização/desativação/remoção em tempo de execução, persistência da configuração e encerramento. Ele não baixa pacotes nem exige uma chave API.

HTTP remoto transmitível

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

O construtor aplica tempos limite às solicitações, cabeçalhos personalizados, tokens bearer, cabeçalhos de chave API personalizados e recuperação limitada quando uma sessão HTTP expira.

OAuth2Config implementa uma solicitação fixa de token de credenciais do cliente OAuth 2.0. Ele é útil para um servidor com um endpoint de token conhecido. Não é o fluxo de autorização MCP completo: não realiza descoberta de metadados de recursos protegidos, descoberta do servidor de autorização, autorização no navegador, PKCE nem negociação de indicadores de recursos. Use a autorização APIs de rmcp ou um componente de identidade externo quando a implantação exigir esse fluxo.

Elucidação

Um servidor MCP pode precisar de informações que não foram incluídas nos argumentos da ferramenta. Nesse caso, ele pode enviar uma solicitação de elucidação de volta ao cliente. A aplicação decide como mostrar a solicitação a uma pessoa e se deve aceitá-la, recusá-la ou cancelá-la.

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

ADK-Rust oferece suporte tanto a formulários quanto à elicitação URL. Um erro ou pânico no manipulador é convertido em uma recusa para que a conexão MCP permaneça utilizável. Valide os valores retornados e aplique as regras de consentimento na aplicação antes de aceitar uma solicitação com consequências.

Consulte examples/mcp_elicitation para ver um servidor completo e um cliente interativo.

Tarefas de longa duração de MCP

MCP 2025-11-25 pode transformar uma chamada de ferramenta em uma tarefa de protocolo. ADK-Rust usa o fluxo de tarefas somente quando o servidor negociou tasks.requests.tools.call e a ferramenta declara suporte obrigatório ou opcional a tarefas.

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 o modo de tarefa, ADK-Rust:

1. envia tools/call com metadados oficiais da tarefa;
2. recebe a tarefa criada;
3. consulta tasks/get usando o intervalo sugerido pelo servidor;
4. lê a carga útil final por meio de tasks/result; e
5. chama tasks/cancel quando o tempo limite local ou o limite de consultas é atingido.

input_required é retornado como um erro tipado porque uma chamada de ferramenta ADK comum ainda não tem um canal de retomada neutro em relação ao protocolo para fornecer essa entrada ausente. Projete essa interação explicitamente no fluxo de trabalho responsável por ela.

Mapa de capacidades

Escolhendo o limite

Use um FunctionTool Rust quando o recurso pertencer ao mesmo processo e lançamento. Use MCP quando outro programa, equipe, linguagem, limite de segurança ou implantação for responsável pelo recurso e dever publicar seu próprio contrato.

Para implantações em produção:

• exponha o menor conjunto de ferramentas útil;
• separe ações somente de leitura e ações consequenciais;
• mantenha os segredos fora dos argumentos da linha de comando e dos arquivos mcp.json versionados;
• autentique servidores HTTP remotos e restrinja o escopo das credenciais;
• trate as descrições das ferramentas e o conteúdo retornado pelo servidor como entradas não confiáveis;
• mantenha a autorização e a aprovação ADK-Rust em torno da execução das ferramentas;
• defina limites para os tempos limite de conexão, ferramenta e tarefa; e
• registre chamadas de ferramentas, aprovações, erros e alterações no ciclo de vida do servidor.

Limitações atuais

• McpServerManager gerencia processos filhos locais de stdio. Serviços HTTP remotos usam McpHttpClientBuilder e configuração pertencente à aplicação.
• As verificações de integridade do gerenciador detectam conexões MCP fechadas; elas não chamam uma ferramenta de integridade no nível de negócio.
• As mutações do registro são serializadas enquanto um filho conclui seu handshake MCP.
• autoApprove é compatibilidade de configuração, não aplicação de autorização.
• O auxiliar OAuth integrado corresponde às credenciais do cliente, não ao fluxo completo de descoberta e autorização do usuário MCP OAuth.

Essas limitações são declaradas para que as decisões de implantação permaneçam explícitas.

Referências

• Especificação MCP 2025-11-25
• SDK oficial do Rust (rmcp)
• Documentação de rmcp 3.1 API
• Normalização de esquema com reconhecimento do provedor