Esta página foi traduzida automaticamente do inglês e pode estar desatualizada. Leia o original
Suporte ao Protocolo de Contexto do Modelo (MCP)
O MCP vincula ferramentas externas a um Gateway de IA. Utilize-o quando o assistente precisar chamar serviços em tempo real por meio de um protocolo de ferramenta padrão.
O protocolo define ferramentas que são executadas no lado do servidor e permitem que o assistente interaja com serviços em tempo real.
O AIVAX atua como cliente MCP para inferência no gateway. Para cada fonte configurada, ele:
- Conecta-se ao servidor MCP.
- Lista as ferramentas.
- Converte o esquema de cada ferramenta em uma função acionável pelo modelo.
- Chama o servidor MCP remoto quando o modelo seleciona essa ferramenta.
Quando usar o MCP #
Use o MCP quando você já tiver ferramentas externas que precisam ser descobertas e chamadas pelos modelos de maneira padronizada. Um servidor MCP se encaixa em:
- Catálogos de ferramentas.
- Integrações com sistemas internos.
- Operações com estado.
- Ferramentas compartilhadas entre vários agentes.
- Ambientes onde você deseja manter a lógica fora do AIVAX.
Não use o MCP apenas para substituir uma única chamada HTTP simples.
- Use funções de protocolo quando precisar de uma função isolada com um callback específico e autenticação nonce. Elas geralmente são mais simples.
- Use ferramentas integradas quando a capacidade já existir no AIVAX, como pesquisa na web, abertura de URL, execução de código ou geração de imagens. Elas geralmente são o caminho mais direto.
- Use o MCP quando houver um conjunto de ferramentas com seus próprios esquemas, quando outro sistema já utiliza o MCP ou quando você deseja que o mesmo servidor seja usado por diferentes clientes.
Em produção, trate o servidor MCP como uma API exposta a um agente:
- Escreva descrições claras das ferramentas.
- Mantenha os esquemas restritivos.
- Configure a autenticação nos cabeçalhos do servidor.
- Não ofereça ferramentas muito genéricas como
execute,requestousearchsem descrições robustas e parâmetros controlados.
Ferramentas ambíguas aumentam as chamadas incorretas. Ferramentas específicas como lookup_customer_by_email ou create_support_ticket ajudam o modelo a decidir melhor.
Uma lista longa de ferramentas também tem um custo: cada ferramenta oferecida ao modelo adiciona seu nome, descrição e esquema a cada solicitação. Para medir essa sobrecarga e reduzi-la, consulte como medir e reduzir tokens de definição de ferramentas.
Escolhendo o nome da função #
Use um nome que indique a ação. Mantenha-o simples e determinístico. Evite nomes difíceis de adivinhar ou que não sugiram o papel da função. Caso contrário, o assistente pode não chamar a função quando deveria.
Para uma função que consulta um usuário em um banco de dados externo, prefira:
search_userquery_user
Evite:
search(implícito, possivelmente ambíguo)search user(nome com caracteres impróprios)
Após definir o nome, escreva a descrição.
Escolhendo a descrição da função #
Use a descrição para informar ao assistente o que a função faz e quando chamá-la.
Inclua:
- Cenários em que o assistente deve chamá-la.
- Cenários em que ela não deve ser chamada.
- Alguns exemplos de chamada única ou regras explícitas da função.
Definindo servidores MCP #
Defina servidores MCP no gateway quando o assistente precisar descobrir e chamar as ferramentas desse servidor. Envie uma matriz JSON:
[
{
"name": "Meu servidor MCP",
"url": "https://example-server.io/mcp",
"headers": {
"Authorization": "<AIVAX_API_KEY>"
}
}
]Seu servidor MCP deve suportar HTTP Streamable para funcionar com o AIVAX como fonte de ferramentas do gateway. Você pode definir cabeçalhos personalizados na configuração do seu servidor MCP para configurar autenticação ou outras necessidades. Ferramentas, instruções do servidor e descoberta de habilidades remotas são armazenadas em cache conforme cacheDuration, separadamente para cada contexto de chamada; o padrão é 600 segundos.
Cada origem MCP aceita os seguintes campos. Use-os para nomear a origem, autenticar a conexão e controlar o que o modelo vê:
| Campo | Tipo | Padrão | Descrição |
|---|---|---|---|
name | string | Obrigatório | Nome de exibição da origem, com pelo menos 3 caracteres. Ele identifica a origem nos nomes das ferramentas (consulte prefixTools), nas instruções do servidor e nas descrições de habilidades remotas. Alterá-lo cria uma nova entrada de cache de descoberta. |
url | string | Obrigatório | URL absoluto HTTP ou HTTPS do ponto de extremidade Streamable HTTP do servidor MCP. |
description | string | null | Nota opcional descrevendo o que a origem fornece. É apenas informativa: não é enviada ao modelo nem ao servidor MCP. |
headers | object | {} | Mapeamento de nomes de cabeçalhos HTTP para valores string enviados em cada conexão com o servidor, tanto durante a descoberta quanto em cada chamada de ferramenta. Use-o para autenticação, como Authorization. |
cacheDuration | integer | 600 | Tempo, em segundos, no qual as ferramentas descobertas, as instruções do servidor e as habilidades remotas são reutilizadas antes que o AIVAX as liste novamente. Aceita valores de 0 a 86400. As chamadas de ferramentas nunca são armazenadas em cache. |
prefixTools | boolean | true | Quando true, cada ferramenta é exposta ao modelo como mcp_<origem>_<ferramenta>, onde <origem> é o name em letras minúsculas, com espaços substituídos por hífens e outros caracteres não alfanuméricos removidos. Por exemplo, a ferramenta get_weather do Meu servidor MCP torna-se mcp_meu-servidor-mcp_get_weather. Quando false, o nome original da ferramenta do servidor é usado; certifique-se de que não haja colisão com ferramentas de outras origens ou funções no mesmo gateway. O servidor sempre recebe seu nome original de ferramenta. |
allowClientInstructions | boolean | true | Adiciona as instruções de uso anunciadas pelo servidor ao contexto do gateway. Consulte instruções do servidor e habilidades remotas. |
allowRemoteSkills | boolean | true | Importa habilidades remotas verificadas de servidores que anunciam a extensão de habilidades. Consulte instruções do servidor e habilidades remotas. |
Se o seu servidor for direcionado ao MCP 2026-07-28, consulte MCP Stateless: migrando do Mcp-Session-Id para ver como ele interage com este gateway.
Instruções do servidor e habilidades remotas #
Use essas opções quando um servidor MCP confiável deve adicionar instruções ou habilidades ao gateway. Cada origem MCP aceita allowClientInstructions e allowRemoteSkills. Ambas estão habilitadas por padrão. Defina qualquer opção como false para excluir esse conteúdo.
Conecte-se apenas a servidores cujo conteúdo você confia:
- As instruções do servidor são adicionadas ao contexto do gateway.
- As habilidades remotas ficam disponíveis por meio de
read_skilljunto com suas habilidades de conta.
Como funciona a descoberta:
- O AIVAX solicita ferramentas apenas quando o servidor anuncia ferramentas.
- A descoberta de habilidades também requer a capacidade
resourcese a extensãoio.modelcontextprotocol/skillsnas capacidades do servidor retornadas durante a inicialização. - O AIVAX segue a paginação de
skills/liste lê cadaSKILL.mdlistado no mesmo servidor. - As habilidades remotas recebem identificadores qualificados por origem para não substituir as habilidades da conta ou habilidades de mesma origem de outra fonte.
Esta é uma integração de compatibilidade limitada, não suporte completo ao protocolo base 2026-07-28 da extensão.
Para saber como o SEP-2640 divide a descoberta, verificação e ativação entre servidor e host, e quais clientes o suportam, consulte Habilidades MCP vs ferramentas.
- O servidor deve aceitar o fluxo de inicialização existente do Streamable HTTP e anunciar a extensão nele.
- Servidores que exigem
server/discovernão são suportados por esta integração.
Apenas o SKILL.md raiz é importado. Seu comprimento em bytes, digest SHA-256 e frontmatter YAML devem corresponder à entrada anunciada. Uma incompatibilidade falha na descoberta em vez de carregar conteúdo não verificado.
Limites e exclusões de importação:
- Os manifestos são limitados a 512 recursos e 16 MiB de conteúdo total declarado por habilidade.
- Habilidades que anunciam
resources: "dynamic"são ignoradas. - Arquivos de suporte, navegação por diretório, busca direta
skills/gete scripts não são importados. - O frontmatter não concede permissões de ferramenta nem preenche as listas de ferramentas permitidas do gateway. As políticas de ferramenta existentes ainda se aplicam.
- Esta integração não adiciona um sistema de aprovação por habilidade nem uma nova sandbox de execução. Desative as habilidades remotas quando sua política exigir esses controles.
Antes de conectar um servidor de terceiros, revise Melhores práticas de segurança do servidor MCP para servidores de terceiros, que cobre envenenamento de ferramentas, credenciais, bloqueio baseado em worker e aprovação no lado do servidor.
As mesmas opções se aplicam às origens MCP adicionadas por trabalhadores do gateway. As habilidades de conta existentes permanecem disponíveis. Novas conexões buscam o conteúdo da habilidade durante a descoberta, enquanto read_skill controla quando esse conteúdo entra no contexto ativo de habilidades do modelo.
Metadados enviados com solicitações MCP #
Use esta seção quando seu servidor MCP precisar identificar o contexto de chamada ou receber valores de aplicativo com uma solicitação.
O AIVAX adiciona o contexto de chamada em params._meta a toda solicitação e notificação que envia ao servidor: initialize, notifications/initialized, tools/list, skills/list, resources/read e tools/call.
- Em
tools/call, os argumentos contêm a entrada da ferramenta. - Os metadados identificam o contexto de chamada e carregam valores fornecidos pelo aplicativo.
- As solicitações de descoberta carregam o contexto da inferência que as acionou. Os resultados são armazenados em cache por contexto de chamada, portanto, uma lista de ferramentas em cache nunca é reutilizada para outro usuário, conversa ou conjunto de metadados.
O exemplo a seguir ilustra uma chamada com um usuário identificado, um token de conversa e metadados personalizados:
{
"jsonrpc": "2.0",
"id": 2,
"method": "tools/call",
"params": {
"name": "get_weather",
"arguments": {
"location": "Nova York"
},
"_meta": {
"_aiv_nonce": "<BCRYPT_HASH>",
"_aiv_external_user_id": "<EXTERNAL_USER_ID>",
"_aiv_call_source": "WebChatClient",
"_aiv_conversation_token": "<CONVERSATION_TOKEN>",
"_aiv_moment": "2025-09-09T16:58:05.0000000+00:00",
"tenant_id": "<TENANT_ID>",
"request_id": "<APPLICATION_REQUEST_ID>"
}
}
}Campos do AIVAX #
Estes campos identificam o contexto de chamada. Todos os caminhos abaixo são relativos a params._meta. Nomes começando com _aiv são reservados; não os use para metadados personalizados.
| Campo | Tipo JSON | Significado e disponibilidade |
|---|---|---|
_aiv_nonce | string ou null | Hash BCrypt derivado da chave de hook da conta de chamada. Sem uma chave de hook configurada, seu valor é null. Verifique a chave de hook em texto claro configurada contra este hash, conforme descrito em autenticação de hook; não compare strings de hash ou espere a própria chave de hook. |
_aiv_external_user_id | string ou null | Identificador de usuário externo carregado pelo contexto de inferência. Para clientes de chat, vem da sessão; para conclusões de chat, vem do campo user da solicitação. Pode ser null quando nenhum usuário foi identificado. Use-o para procurar o usuário em seu aplicativo, não como ID de conta AIVAX ou prova de autorização. |
_aiv_call_source | string | Origem da inferência, não o transporte de ferramenta de saída. Uma ferramenta MCP chamada durante a inferência de bate-papo na web ainda recebe WebChatClient, não McpClient. Consulte os valores abaixo. |
_aiv_conversation_token | string ou null | Token de correlação de conversa carregado pela sessão ou solicitação de inferência. Para conclusões de chat, é o conversation_token da solicitação, ou o token gerado pelo AIVAX quando nenhum foi enviado. Pode ser null; não é uma credencial de autenticação nem um ID de chamada de ferramenta exclusivo. Várias chamadas na mesma conversa podem compartilhá-lo. |
_aiv_moment | string | Carimbo de data/hora criado quando o AIVAX abre a conexão que envia esta solicitação, no formato ISO 8601 de ida e volta com frações de segundo e deslocamento UTC. Usa o relógio local do servidor AIVAX, não o fuso horário do usuário ou o início da conversa. Analise o deslocamento e converta para o fuso horário do seu aplicativo quando necessário. |
Valores de origem de chamada #
Use a origem para rotear e diagnosticar a chamada, não para autorizar. Os mesmos valores de string são usados por funções de protocolo em context.callSource:
| Valor | Origem da inferência |
|---|---|
WebChatClient | Cliente de bate-papo na web do AIVAX. |
ChatCompletionsApi | API de conclusões de chat compatível com OpenAI; a origem padrão para essa API. |
FunctionsApi | API de funções. |
IntegrationBot | Bot de integração de mensagens. |
OpenWebUiClient | Cliente Open WebUI. |
McpClient | Inferência iniciada por meio de um cliente MCP. |
ValidationApi | Validação de teste agêntico. |
Os consumidores devem tolerar valores de origem futuros.
Metadados personalizados e segurança #
Os metadados de inferência personalizados são um mapa de chaves string para valores string. Eles vêm dos metadados de solicitação para conclusões de chat ou de metadados de sessão para clientes de chat, incluindo sessões criadas por integrações de mensagens.
O AIVAX copia essas entradas diretamente em params._meta. Chaves personalizadas começando com _aiv são ignoradas e nunca substituem os campos do AIVAX. No exemplo, tenant_id e request_id são definidos pelo aplicativo, não são campos nativos do AIVAX. Não há objeto metadata aninhado no envelope MCP. Sem metadados personalizados, apenas os campos do AIVAX permanecem.
Antes de confiar nos metadados:
- Não envie segredos em metadados personalizados. Esses valores são encaminhados ao servidor de ferramenta remoto.
- Valide o acesso do tenant e do usuário contra seus próprios registros confiáveis antes de usar metadados para selecionar dados ou realizar gravações.
- Não trate um ID de usuário externo, um token de conversa ou um rótulo de origem de chamada como permissão por si só.
- Trate o nonce como prova apenas da chave de hook da conta configurada. Não é uma assinatura dos argumentos, um ID de solicitação único ou um mecanismo de prevenção de replay.
- Mantenha o HTTPS e os cabeçalhos de autenticação configurados do servidor MCP.
- Aplique seus próprios controles de autorização e de operações duplicadas.
- Se o seu servidor exigir autenticação nonce, rejeite um nonce ausente ou inválido.
Para o envelope de callback HTTP equivalente, consulte contexto de função de protocolo.
Resultados de ferramentas #
Um resultado de ferramenta é o que o servidor MCP retorna após uma chamada. O AIVAX adiciona blocos suportados de volta à conversa para que o modelo possa continuar.
- O texto é adicionado diretamente ao resultado da ferramenta.
- Blocos de imagem e áudio são anexados de volta à conversa como conteúdo multimodal com IDs gerados.
- Tipos de bloco de conteúdo não suportados são relatados como texto não suportado.
Se algo der errado, verifique o sintoma:
- A ferramenta não aparece para o modelo: verifique se o servidor remoto está acessível, suporta Streamable HTTP, possui os cabeçalhos de autenticação corretos e está configurado como uma origem MCP no gateway.
- A ferramenta aparece, mas não é chamada: revise o nome, a descrição e o esquema.
- A ferramenta é chamada com argumentos ruins: restrinja o JSON Schema e inclua descrições de propriedades.
- A chamada falha: faça o servidor MCP retornar erros legíveis para que o modelo possa decidir se tenta outro argumento, pede informações ao usuário ou interrompe a ação.
