Conexões MCP
Uma conexão MCP é um servidor MCP reutilizável do projeto: o endereço, a credencial e o cache de ferramentas ficam guardados uma vez e podem ser usados por vários agentes. É o lugar certo para servidores com OAuth, que exigem autorização pelo navegador, e para não repetir a mesma configuração em cada agente.
Se você quer usar a SIPPulse AI de dentro de outro cliente MCP, veja MCP remoto. Aqui o sentido é o oposto: seus agentes consumindo servidores MCP externos.
O que é uma conexão MCP
Uma conexão pertence ao projeto ativo. Criada sem projeto ativo, ela fica disponível para toda a organização. Cada conexão guarda:
| Campo | O que é |
|---|---|
| Nome | Como a conexão aparece na lista e nos agentes |
| URL | O endpoint MCP do servidor |
| Transporte | Negociado automaticamente (Streamable HTTP com fallback para HTTP+SSE) |
| Autenticação | Sem credencial, cabeçalhos com referências a secrets, ou OAuth 2.1 |
| Cache de tools | As ferramentas descobertas no último Conectar, Testar ou Sincronizar |
Nos cabeçalhos, você referencia secrets do projeto com a sintaxe {{$NOME_DO_SECRET}}; o valor real é resolvido em memória apenas na hora da chamada. Veja o Cofre de Secrets.
Criar e conectar
O modal segue o modelo "informe a URL e clique em Conectar":
- Abra Configurações > Conexões MCP e clique em Criar conexão.
- Informe a URL. O Nome é opcional: se ficar vazio, a plataforma usa o nome informado pelo próprio servidor.
- Se o servidor exigir autenticação por cabeçalho, abra Cabeçalhos (opcional) e adicione as referências a secrets.
- Clique em Conectar. A plataforma negocia o transporte, descobre as ferramentas e, se o servidor pedir credencial, abre a página de autorização do provedor em um popup.
O transporte é decidido automaticamente: o padrão tenta Streamable HTTP e cai para HTTP+SSE quando o servidor não aceita o primeiro. Não é preciso escolher.
Status da conexão
O selo de status diz se a credencial existe e como foi a última verificação:
| Selo | Significado |
|---|---|
| Conectada | A credencial existe e a última verificação funcionou |
| Não conectada | Ainda não há credencial ou o servidor nunca foi verificado |
| Precisa reautenticar | O servidor recusou a credencial; reconecte |
| Erro | A última verificação falhou; o detalhe aparece no item |
Ações da conexão
| Ação | O que faz |
|---|---|
| Conectar | Abre a página de autorização do provedor em um popup e guarda a credencial |
| Reautenticar | Refaz a autorização OAuth de uma conexão já autorizada |
| Revogar | Descarta a credencial local; a conexão volta a não configurada |
| Sincronizar tools | Atualiza o cache de ferramentas do servidor |
| Testar | Conecta, descobre as ferramentas e atualiza o status e o cache |
| Editar | Muda nome, URL e cabeçalhos. Alterar URL ou credenciais exige reconectar |
| Excluir | Remove a conexão. Bloqueada enquanto um ou mais agentes a referenciam |
Ao tentar excluir uma conexão em uso, a plataforma responde: "Esta conexão MCP é usada por um ou mais agentes. Remova-a deles primeiro."
O cache de ferramentas só muda por ação explícita: Sincronizar, Testar, Conectar ou salvar o agente. Ele não expira sozinho.
Usar em agentes
No modal de Servidores MCP do agente:
- Informe nome, URL, transporte (
autopor padrão) e cabeçalhos, ou escolha uma conexão existente no seletor use uma conexão já existente. - Clique em Conectar para descobrir as ferramentas.
- Ligue ou desligue ferramentas individuais. A lista de ferramentas permitidas fica no agente: uma ferramenta nova descoberta na conexão não é habilitada sozinha nos agentes que a usam.
- Clique em Salvar.
Entradas de servidor inline, sem conexão, continuam funcionando para quem já as tem. Conectar uma entrada inline transforma ela em uma conexão.
Quando o provedor revoga o token
Se o provedor revogar a credencial, a conexão passa a Precisa reautenticar. Durante uma execução o agente nunca abre um navegador: a ferramenta responde com o erro mcp_auth_required e a conversa continua. Basta reconectar a conexão para voltar a funcionar.
Compartilhar entre agentes
Uma conexão pode ser usada por vários agentes ao mesmo tempo. Trocar a credencial vale para todos, porque todos usam a mesma conexão. Ao alterar URL ou credenciais, as sessões antigas são descartadas e a plataforma pede reconexão.
Segurança
Credenciais OAuth ficam criptografadas e nunca são devolvidas pela API. As referências {{$NOME_DO_SECRET}} são resolvidas somente na memória, no momento da chamada, e a configuração persistida mantém apenas o placeholder.
Documentação relacionada
- Servidores MCP - o que é MCP e como configurar um servidor
- MCP remoto - usar a SIPPulse AI de dentro de outro cliente MCP
- Ferramentas do agente - visão geral das ferramentas
- Cofre de Secrets - guardar e referenciar credenciais