Fontes de ferramentas (MCP)

Uma fonte de ferramentas é um serviço externo que a plataforma conecta ao seu agente para ampliar o que ele consegue fazer: buscar na web, consultar um sistema interno, ler documentos, criar registros. Cada fonte fala o padrão aberto MCP (Model Context Protocol) e expõe uma ou mais ferramentas, que o agente aciona durante a conversa.

Esta página explica como uma fonte de ferramentas é configurada, como o agente faz referência às ferramentas dela e — o ponto principal — como a plataforma se autentica na fonte para usá-la em seu nome.

Procurando uma ferramenta pronta?

Você não precisa hospedar nada para usar as fontes MCP publicadas por terceiros. O guia Conectar ferramentas prontas mostra onde encontrá-las e como ligá-las em poucos passos.

Como o agente usa uma ferramenta

Cada especialista lista, no campo tools, as ferramentas que pode acionar, no formato fonte.ferramenta:

tools:
  - tavily.tavily_search
  - tavily.tavily_extract

• fonte é o nome da fonte de ferramentas conectada à plataforma (aqui, tavily).
• ferramenta é a capacidade específica que aquela fonte expõe (aqui, tavily_search).

Só listar a ferramenta não garante que o agente a use no momento certo — descreva no prompt quando e como acioná-la. Veja a configuração do especialista para o campo tools no contexto do arquivo completo.

Anatomia de uma fonte de ferramentas

Uma fonte é definida por poucos atributos:

Atributo	Obrigatório	Descrição
Nome	✅	Identificador da fonte. É o prefixo usado em tools (nome.ferramenta). Use apenas letras, números, - e _ — sem ponto.
Endereço	✅	O endereço (URL https://) onde a fonte MCP responde.
Autenticação	—	Como a plataforma se autentica na fonte. Padrão: nenhuma. Veja abaixo.
Acesso sem usuário identificado	—	Se a fonte pode ser usada em conversas sem usuário identificado, e com que alcance. Padrão: Não permitir. Veja abaixo.
Protocolo novo (negociação automática)	—	Desligada por padrão. Ligada, a plataforma passa a falar com a fonte na versão mais nova do protocolo aberto sempre que ela estiver disponível, e volta sozinha para a versão anterior quando não — ligar é seguro em qualquer fonte. Necessário para perguntas no meio da conversa.

O catálogo de ferramentas (quais ferramentas existem e o que cada uma recebe) é descoberto automaticamente a partir da fonte — você não precisa declará-lo. Se a fonte estiver fora do ar quando o agente tentar usá-la, a chamada da ferramenta falha; a conversa continua e o agente segue com o que tem.

Modos de autenticação

A maioria das fontes exige credencial. A plataforma oferece quatro modos — escolha conforme de quem é a credencial e como ela chega até a fonte.

Credencial gerenciada pela plataforma

Uma credencial única, guardada pela plataforma e compartilhada por todas as conversas. É o modo mais simples: todos os usuários acessam a fonte com a mesma identidade de aplicação.

Usado em fontes de alcance geral, mantidas centralmente pela plataforma (por exemplo, uma busca na web comum a todos os agentes). Fontes específicas da sua organização não usam este modo — para elas, use uma das opções abaixo.

Sua própria chave

A plataforma usa uma chave de API sua para acessar a fonte. Você fornece a chave uma vez por um canal seguro; a partir daí, as chamadas àquela fonte usam essa credencial.

Use quando a fonte é um serviço em que você tem conta e cobrança próprias (sua conta de busca, seu provedor de dados) e quer que o consumo corra por ela.

Conectar sua conta (OAuth)

A fonte pede que cada usuário autorize o acesso à própria conta, no mesmo modelo dos "conectores": na primeira vez que o agente precisa da ferramenta, o usuário é levado à tela de login do provedor, concede a autorização e a plataforma passa a agir em nome dele.

A autorização é por usuário: dois usuários da mesma organização podem estar conectados a contas diferentes do mesmo serviço (por exemplo, espaços de trabalho distintos), cada um com seu próprio acesso.

Depois de conectada, a autorização é renovada automaticamente enquanto continuar válida. Se ela expirar ou for revogada no provedor, o agente pede a reconexão da mesma forma — basta autorizar de novo.

Identidade do usuário da conversa

A plataforma repassa à fonte a própria credencial do usuário que está na conversa. Serve quando a fonte é um serviço que já conhece esse usuário e deve aplicar exatamente as permissões dele.

Diferente de "conectar sua conta", aqui não há uma tela de autorização separada: a identidade que já autentica a conversa é reaproveitada na chamada à ferramenta.

Sem autenticação

Fontes públicas podem dispensar credencial. Nesse caso, nenhuma identidade é enviada.

Resumo

Modo	De quem é a credencial	Quando usar
Gerenciada pela plataforma	Da plataforma, compartilhada	Fontes gerais mantidas centralmente.
Sua própria chave	Sua (uma chave, por organização)	Serviço com sua conta e cobrança próprias.
Conectar sua conta (OAuth)	De cada usuário (login no provedor)	Fonte que age na conta pessoal de cada usuário.
Identidade do usuário	Do usuário da conversa	Fonte que já conhece o usuário e aplica as permissões dele.
Sem autenticação	Nenhuma	Fontes públicas.

Credenciais são somente-escrita

Qualquer credencial que você fornece (uma chave própria, um segredo de OAuth) é somente-escrita: a plataforma a guarda de forma cifrada e nunca a devolve em telas ou respostas. Ao consultar uma fonte, você vê apenas o tipo de autenticação e se há uma credencial configurada — nunca o valor. Para trocar uma credencial, basta enviar a nova.

Acesso sem usuário identificado

Algumas conversas acontecem sem um usuário identificado — por exemplo, um agente público. Cada fonte declara, no campo Acesso sem usuário identificado, se pode ser usada nessas conversas e com que alcance:

Opção	Efeito em conversa sem usuário identificado
Não permitir	Nenhuma ferramenta da fonte é acionável. É o padrão.
Permitir apenas leitura (segundo o que a fonte declara)	Só as ferramentas que a fonte declara como somente-leitura.
Permitir tudo	Qualquer ferramenta da fonte, inclusive as que alteram ou apagam.

O campo apenas restringe: a ferramenta ainda precisa estar no tools do especialista para ser acionada. Conversas com usuário identificado não são afetadas por ele.

Como a leitura é determinada

A plataforma usa a anotação readOnlyHint que a própria fonte publica junto de cada ferramenta no catálogo. É uma declaração da fonte, não uma verificação da plataforma: um servidor de terceiro pode marcar como leitura uma ferramenta que na verdade escreve ou apaga.

O critério é fechado por padrão — só conta como leitura a ferramenta cuja anotação seja explicitamente verdadeira. Ferramenta sem anotação é tratada como escrita e fica de fora do modo apenas leitura. A anotação restringe, nunca amplia.

Na lista de ferramentas de uma fonte, cada uma aparece marcada como leitura, escrita ou destrutiva, sempre segundo essa declaração.

Modos de autenticação incompatíveis

Modos que dependem da identidade do usuário (conectar sua conta, identidade do usuário) não funcionam em conversas sem usuário identificado, porque não há usuário para autorizar — qualquer que seja o valor deste campo.

Exemplo completo

Um especialista de pesquisa que usa uma fonte de busca na web:

id: pesquisador-web
version: "1.0.0"
kind: specialist

model:
  default: default
  fallback: default

tools:
  - tavily.tavily_search
  - tavily.tavily_extract

prompt: |
  Você é um assistente de pesquisa. Quando a pergunta exigir informação atual,
  use `tavily_search` para buscar e `tavily_extract` para ler URLs específicas.
  Escreva uma resposta concisa e sempre cite as fontes (URLs).

installed_skills: []

cost_cap:
  per_conversation: 1.00

A fonte tavily é configurada uma vez (endereço + modo de autenticação) e fica disponível para qualquer especialista referenciá-la no campo tools.

Fontes da plataforma

Além de fontes externas que você conecta, a plataforma já vem com fontes prontas para trabalhar com anexos e dados — sem configuração de endereço nem autenticação:

• Anexos da conversa — ler e transformar o arquivo que a pessoa enviou.
• Base de conhecimento — guardar e consultar documentos.
• Análise de dados — analisar planilhas e tabelas.

Os nomes exatos das fontes são os que aparecem na tela de fontes de ferramentas do painel. Veja Anexos de conversa para a receita de uso em conversa.

Prompts prontos

Além das ferramentas, uma fonte pode publicar prompts prontos: instruções que os próprios autores da fonte já escreveram para o assunto dela — um roteiro de "resumo executivo de um documento", por exemplo. Um prompt pronto anexado a um especialista se comporta como uma habilidade: o agente pode abri-lo e segui-lo durante a conversa.

Anexar não é automático — mesmo com a fonte já em tools, cada prompt precisa ser anexado à parte, no campo installed_prompts do especialista. Veja Prompts prontos de uma fonte para como.

Perguntas frequentes

O agente respondeu que precisa de autorização — o que fazer? A ferramenta usa o modo conectar sua conta e ainda não foi autorizada (ou a autorização expirou). Faça o login no provedor quando a plataforma oferecer, e o agente retoma de onde parou.

Adicionei uma ferramenta em tools e o agente não a usa. Verifique se o nome está no formato fonte.ferramenta e se o prompt orienta quando usá-la. Se a fonte referenciada não existir, aquela ferramenta é ignorada e a conversa segue sem ela.

Posso apontar uma fonte para um endereço interno? Não. O endereço precisa ser um https:// acessível publicamente; endereços de rede interna são recusados por segurança.

A fonte pode perguntar algo no meio da conversa? Pode, se a opção Protocolo novo (negociação automática) estiver ligada e a conversa tiver um usuário identificado. Veja Quando a ferramenta precisa perguntar algo.