Conectores personalizados

Um conector personalizado permite que um admin da organização registre uma API HTTPS ou, onde habilitado, um servidor MCP HTTP streamable que não esteja no catálogo integrado. Ele define a fronteira de rede e o método de autenticação. Ele não gera automaticamente uma referência de API completa para o agente.

Quem configura o quê

• Admins da organização criam, editam e excluem a definição do conector.
• Membros conectam seu próprio segredo ou concluem o fluxo OAuth do conector.
• Autorização do agente controla quais agentes podem usar a credencial conectada e quais permissões nomeadas recebem.

A definição é compartilhada na organização. As credenciais dos membros permanecem limitadas ao membro e à organização.

Conector de API HTTP

1. Abra Connectors → Custom e escolha New connector.
2. Selecione HTTP API e insira um nome de exibição.
3. Adicione um ou mais Prefixes HTTPS, um por linha. Uma solicitação deve corresponder a um prefixo configurado antes que o conector possa autorizá-la.
4. Adicione autenticação se a API precisar:
   • API authentication: insira o nome do cabeçalho e um modelo de cabeçalho contendo {{secret}}, por exemplo Authorization e Bearer {{secret}}.
   • OAuth 2.0: insira a URL de autorização, a URL de token, o client ID, o client secret, os escopos e o método de autenticação do endpoint de token. Registre a URL de redirecionamento exata mostrada no formulário com o provedor.
5. Crie o conector. Cada membro que precisar dele então seleciona Connect e fornece seu segredo ou conclui o OAuth.
6. Autorize o agente e as permissões necessárias.

Alterar uma definição OAuth existente ou suas credenciais de cliente desconecta as conexões OAuth atuais. Os membros precisam se reconectar após a alteração.

Conector MCP

Se MCP aparecer como tipo de conector no seu espaço de trabalho, insira um endpoint MCP HTTP streamable HTTPS e configure a autenticação API ou OAuth no mesmo formulário. Se MCP não for oferecido no seletor, ele não está habilitado para aquele espaço de trabalho.

Ensine ao agente o procedimento da API

Um conector personalizado fornece acesso de rede seguro e injeção de credencial. O formulário de criação não faz upload nem detecta automaticamente um documento OpenAPI. Dê ao agente o endpoint, o método, os parâmetros e a resposta esperada na solicitação, ou registre esse procedimento em um fluxo de trabalho com uma referência de API anexada como arquivo.

Valide um novo conector com uma solicitação estreita e somente leitura a um endpoint conhecido. Não existe uma solicitação genérica Test connection porque muitas APIs não expõem um endpoint raiz significativo.

Fronteiras de segurança

• Apenas prefixos HTTPS e endpoints MCP são aceitos.
• O firewall injeta a credencial salva apenas em solicitações correspondentes.
• O segredo salvo é criptografado em repouso e não é exposto ao agente como variável de ambiente.
• Não coloque chaves, tokens ou segredos de cliente em mensagens de chat, instruções de fluxo de trabalho ou arquivos anexados.
• Use uma credencial de serviço com os escopos upstream mínimos necessários ao fluxo de trabalho.

Solução de problemas

Próximo

• Veja Workflows para registrar trabalho repetido de conector personalizado.
• Veja Permissions para como as credenciais de conectores personalizados são tratadas.
• Veja o Catalog antes de criar o seu — seu serviço pode já ser suportado.