Servidor MCP (IA / Agentes)

Visao Geral

O servidor MCP da Paralela permite que clientes de IA e agentes externos (como o Claude Desktop, ou produtos proprios) operem a plataforma por conta do usuario, conversando em linguagem natural. Ele expoe, por meio do Model Context Protocol (MCP), exatamente as mesmas acoes do Copilot interno: atendimentos, contatos, campanhas, fluxos do flow builder, kanban, tarefas, agentes de IA, loja, relatorios e muito mais.

Em outras palavras: tudo o que o Copilot faz dentro do sistema, um agente externo tambem consegue fazer pelo MCP — respeitando as permissoes do usuario dono do token.

Endpoint

POST /mcp

• Transporte: Streamable HTTP (Model Context Protocol).
• Modo: stateless — cada requisicao e independente, sem sessao persistente entre chamadas.
• A URL completa e o endereco do seu backend seguido de /mcp (ex.: https://api.suaempresa.com/mcp).

Autenticacao

Toda requisicao precisa enviar um token MCP no cabecalho de autorizacao:

Authorization: Bearer mcp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

O token e vinculado a um usuario e a uma empresa. O agente herda as permissoes desse usuario — ele so consegue executar o que o usuario poderia executar na interface. Use um usuario com o nivel de acesso adequado ao que o agente precisa fazer.

Tokens MCP

Pela interface (recomendado)

Acesse API de Mensagens → Servidor MCP (IA). A secao Tokens MCP lista os tokens da empresa (nome, data de criacao, ultimo uso e situacao) e permite:

• Criar um token: clique em Novo token, de um nome que identifique onde ele sera usado (ex.: "Claude Desktop do Joao") e confirme. O token aparece uma unica vez, junto com a configuracao pronta para colar no cliente de IA — copie os dois antes de fechar a janela.
• Revogar um token: clique no icone de lixeira. Qualquer cliente que use aquele token perde o acesso imediatamente.

Crie um token por cliente de IA. Assim voce revoga o acesso de um sem derrubar os demais.

A secao so aparece para quem tem permissao de administrador (company_settings:manage).

Pela API

As mesmas operacoes estao disponiveis via HTTP, para automatizar o provisionamento. Todas exigem company_settings:manage.

Criar um token

POST /mcp-tokens
Authorization: Bearer SEU_JWT
Content-Type: application/json

{ "name": "Claude Desktop" }

Resposta (o token e exibido apenas uma vez — guarde-o com seguranca):

{
  "id": 1,
  "name": "Claude Desktop",
  "enabled": true,
  "token": "mcp_3f8a...c2"
}

O sistema nunca armazena o token em texto puro (apenas o hash), por isso ele nao pode ser recuperado depois. Se perder o token, crie um novo e exclua o antigo.

Listar tokens

GET /mcp-tokens
Authorization: Bearer SEU_JWT

Retorna os tokens da empresa (nome, status, ultimo uso) — sem o segredo.

Revogar um token

DELETE /mcp-tokens/:id
Authorization: Bearer SEU_JWT

Exclui o token permanentemente, derrubando o acesso de qualquer cliente que o estivesse usando.

Conectando um cliente

Ao criar um token pela interface, o sistema ja monta esta configuracao preenchida com a URL e o token — basta copiar. O exemplo abaixo mostra o formato para o Claude Desktop, usando o conector mcp-remote (encaminha o cabecalho de autorizacao para o servidor HTTP):

{
  "mcpServers": {
    "paralela": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://api.suaempresa.com/mcp",
        "--header",
        "Authorization: Bearer mcp_SEU_TOKEN"
      ]
    }
  }
}

Outros clientes MCP que suportam o transporte Streamable HTTP podem se conectar diretamente ao endpoint /mcp enviando o mesmo cabecalho Authorization.

Permissoes e seguranca

• Respeita as permissoes do usuario. O agente atua dentro do perfil do usuario dono do token; acoes negadas por permissao continuam negadas pelo MCP.
• Isolamento por empresa. O agente so enxerga e altera dados da empresa do token.
• Confirmacao de acoes sensiveis. Acoes que enviam mensagens ao cliente, excluem dados ou agem em massa exigem confirmacao: a ferramenta responde pedindo confirmacao e so executa quando chamada novamente, em uma chamada seguinte, com os mesmos parametros. Isso evita execucoes acidentais.
• Revogacao imediata. Excluir o token bloqueia na hora qualquer cliente que o utilize.

O que o agente pode fazer

A lista de capacidades e a mesma do Copilot. Veja a documentacao do Copilot para a relacao completa — atendimentos, contatos, campanhas e disparos, fluxos do flow builder (criar, editar, templates, versoes), kanban e tarefas, agentes de IA, e-mail marketing, loja, conexoes de WhatsApp, leads e formularios, relatorios, entre outras.

Diferenca para a API de Mensagens

A API de Mensagens e ideal para integracoes diretas e deterministicas (enviar uma mensagem, criar um lead, verificar um numero) a partir de outro sistema. O servidor MCP e voltado para agentes de IA que decidem, em linguagem natural, quais acoes executar — cobrindo um conjunto muito maior de operacoes da plataforma.