MCP remoto

O MCP remoto permite usar a SIPPulse AI de dentro de um cliente MCP: Claude, Cursor, VS Code, ChatGPT ou qualquer cliente que fale Streamable HTTP com descoberta OAuth. Você autoriza pelo navegador, escolhe a organização e o projeto, e o cliente passa a ter as ferramentas da plataforma.

Todas as conexões usam a mesma URL:

https://api.sippulse.ai/mcp

Este é o servidor MCP da própria SIPPulse AI. Para conectar seus agentes a servidores MCP de terceiros, veja Servidores MCP e Conexões MCP.

Como a conexão funciona

O cliente MCP descobre a configuração OAuth sozinho, a partir da URL do MCP:

1. O cliente acessa a URL e recebe a indicação do servidor de autorização.
2. O navegador abre a tela de consentimento da SIPPulse AI.
3. A tela mostra a aplicação que está pedindo acesso, a organização, o projeto e as permissões envolvidas.
4. Você aprova ou nega. Ao aprovar, o cliente recebe um token e já pode chamar as ferramentas.
5. A renovação do token é automática enquanto o acesso continuar válido.
6. Se o token expirar ou for revogado, o cliente pede autorização de novo.

Cada consentimento fica vinculado a uma organização e a um projeto acessível por você. O acesso combina o seu papel atual na organização com as permissões concedidas. Não é possível ampliar o acesso depois: para dar mais permissões, é preciso autorizar de novo.

Configurar o cliente

Claude Code

claude mcp add --transport http sippulse https://api.sippulse.ai/mcp

Cursor e VS Code

No arquivo mcp.json do cliente:

{
  "servers": {
    "sippulse": {
      "type": "http",
      "url": "https://api.sippulse.ai/mcp"
    }
  }
}

Claude.ai (conector personalizado)

No Claude.ai, adicione um conector MCP personalizado e cole https://api.sippulse.ai/mcp como endereço do servidor. Outros clientes que aceitam um conector personalizado, como o ChatGPT, usam a mesma URL e o mesmo fluxo de autorização no navegador.

API key para automação

Para automações que não passam por consentimento interativo, use uma chave API no header Authorization:

Authorization: Bearer <sua_chave_api>

Uma chave API vinculada a um projeto fixa esse projeto e não pede escolha no navegador. Ela dá acesso ao catálogo completo de ferramentas do MCP, então guarde-a como qualquer outra credencial. A chave precisa ter as mesmas permissões que a ferramenta exige: a plataforma verifica o RBAC da chave, e uma chave API não ignora as permissões.

Permissões (escopos)

Escopo	O que permite
spai:agents:read	Ler agentes e o catálogo de ferramentas internas
spai:agents:write	Criar, editar, validar e excluir agentes
spai:agents:execute	Executar um turno real em uma thread
spai:secrets:read	Ver apenas os nomes dos secrets do projeto
spai:channels:read	Ler implantações de SIP, WhatsApp e Telegram
spai:channels:write	Criar, editar, ativar, desativar e excluir implantações
spai:threads:read	Ler metadados de threads e um trecho do histórico
spai:threads:write	Criar, fechar e excluir threads
spai:models:read	Ler o catálogo de modelos da organização

Ler, escrever e executar são permissões diferentes: leitura nunca altera nada, escrita cria e modifica, e execução roda de fato um turno. Uma autorização somente leitura não altera nada, nem para owners e admins.

Ferramentas disponíveis

Todas as ferramentas são expostas pelo próprio MCP. A coluna Custo indica se a chamada consome créditos da sua organização.

Agentes

Ferramenta	O que faz	Escopo	Custo
agents_list	Lista os agentes do projeto efetivo	spai:agents:read	Não
agents_get	Retorna um agente já sanitizado	spai:agents:read	Não
agents_validate	Valida a configuração de modelo sem gravar o agente	spai:agents:write	Não
agents_create	Cria um agente sem aceitar material secreto	spai:agents:write	Não
agents_update	Atualiza um agente sem aceitar material secreto	spai:agents:write	Não
agents_delete	Exclui um agente após confirmação explícita	spai:agents:write	Não
internal_tools_list	Lista o catálogo de ferramentas internas do agente	spai:agents:read	Não

Modelos

Ferramenta	O que faz	Escopo	Custo
models_list	Lista os modelos da organização e suas capacidades	spai:models:read	Não
models_get	Retorna um modelo e o esquema de parâmetros do agente	spai:models:read	Não

Secrets

Ferramenta	O que faz	Escopo	Custo
secrets_list	Lista apenas os nomes dos secrets; valores e metadados nunca são retornados	spai:secrets:read	Não

SIP

Ferramenta	O que faz	Escopo	Custo
sip_deployments_list	Lista as implantações SIP	spai:channels:read	Não
sip_deployments_get	Retorna uma implantação SIP	spai:channels:read	Não
sip_deployments_apply	Aplica uma implantação SIP usando referências a secrets do projeto	spai:channels:write	Não

WhatsApp

Ferramenta	O que faz	Escopo	Custo
whatsapp_deployments_list	Lista as implantações de WhatsApp	spai:channels:read	Não
whatsapp_deployments_get	Retorna uma implantação de WhatsApp	spai:channels:read	Não
whatsapp_deployments_create	Cria uma implantação de WhatsApp	spai:channels:write	Não
whatsapp_deployments_update	Atualiza uma implantação de WhatsApp	spai:channels:write	Não
whatsapp_deployments_activate	Ativa uma implantação de WhatsApp	spai:channels:write	Não
whatsapp_deployments_deactivate	Desativa uma implantação de WhatsApp	spai:channels:write	Não
whatsapp_deployments_delete	Exclui uma implantação de WhatsApp após confirmação explícita	spai:channels:write	Não

Telegram

Ferramenta	O que faz	Escopo	Custo
telegram_deployments_list	Lista as implantações de Telegram	spai:channels:read	Não
telegram_deployments_get	Retorna uma implantação de Telegram	spai:channels:read	Não
telegram_deployments_create	Cria uma implantação de Telegram usando nomes de secrets	spai:channels:write	Não
telegram_deployments_update	Atualiza uma implantação de Telegram	spai:channels:write	Não
telegram_deployments_activate	Ativa uma implantação de Telegram	spai:channels:write	Não
telegram_deployments_deactivate	Desativa uma implantação de Telegram	spai:channels:write	Não
telegram_deployments_delete	Exclui uma implantação de Telegram após confirmação explícita	spai:channels:write	Não

Threads

Ferramenta	O que faz	Escopo	Custo
threads_list	Lista metadados de threads, sem histórico	spai:threads:read	Não
threads_get	Retorna uma thread sanitizada e limitada	spai:threads:read	Não
threads_create	Cria uma thread para um agente	spai:threads:write	Não
threads_run	Executa um turno em uma thread	spai:agents:execute	Sim
threads_close	Fecha uma thread	spai:threads:write	Não
threads_delete	Exclui uma thread após confirmação explícita	spai:threads:write	Não

threads_run é a única ferramenta que roda um turno de verdade e é cobrada como uma execução normal do agente. agents_validate apenas confere a configuração, sem inferência paga.

O que o MCP remoto nunca faz

• Nunca retorna valores de secrets. secrets_list traz somente os nomes.
• Nunca exclui sem confirmação: agents_delete e threads_delete exigem confirm: true no pedido.
• threads_list nunca carrega o histórico, apenas metadados. threads_get devolve um trecho limitado e sanitizado da conversa.
• Não expõe transcrição de áudio (STT).
• Não tem ferramenta de streaming: cada chamada é uma requisição JSON.

Erros comuns

Erro	O que significa
401	A sessão expirou ou foi revogada. Autorize o cliente de novo.
403 insufficient_scope	A autorização não tem a permissão pedida. Autorize de novo incluindo essa permissão.

Nunca compartilhe tokens de acesso nem chaves API. Quem tem o token usa o MCP com as suas permissões. Se um token vazar, revogue o acesso imediatamente.

Revogar o acesso

Você revoga qualquer autorização a qualquer momento em Configurações > Acessos OAuth. Veja Acessos OAuth. A revogação é imediata: a partir do próximo pedido, o cliente precisa autorizar de novo.

Nota de protocolo

O MCP remoto usa o protocolo MCP 2026-07-28 em modo stateless, sem afinidade de sessão entre requisições.