Servidor MCP (IA / Agentes)

Visão Geral

O servidor MCP da Paralela permite que clientes de IA e agentes externos (como o Claude Desktop, ou produtos próprios) operem a plataforma por conta do usuário, conversando em linguagem natural. Ele expõe, por meio do Model Context Protocol (MCP), exatamente as mesmas ações do Assistente Paralela (Copilot) interno, como ferramentas (tools) que o agente pode chamar.

Em outras palavras: tudo o que o Assistente Paralela faz dentro do sistema, um agente externo também consegue fazer pelo MCP, respeitando as permissões do usuário dono do token.

O que um agente consegue fazer

São cerca de 200 ferramentas, agrupadas nas áreas abaixo. Cada área está descrita em O que ele consegue fazer.

Área	Exemplos do que o agente faz
Atendimentos	Listar, ler a conversa e o histórico, enviar mensagem, transferir, mudar status, notas, ligar/parar IA e fluxo, ações em massa
Contatos	Buscar, criar, editar, bloquear, tags, responsável, ações em massa por filtro
Campanhas e disparos	Criar, editar, cancelar, reenviar, relatório; campanhas recorrentes; prospecção; agendamentos
Busca de leads com IA	Planejar, iniciar, revisar e importar leads como contatos
Flow Builder	Criar e editar fluxos, modelos, versões, categorias e gatilhos por frase
Agentes de IA	Criar e editar agentes, ferramentas HTTP e gatilhos
Kanban e tarefas	Mover cards, criar e atualizar tarefas
E-mail marketing	Campanhas, modelos, estatísticas, e-mail de teste
Loja	Produtos, pedidos, pagamento, link de pagamento
Conexões de WhatsApp	Listar, reiniciar, sincronizar modelos, enviar notificação
Cadastros	Filas, tags, respostas rápidas, campos personalizados, usuários
Relatórios	Desempenho, tempos de resposta, motivos de encerramento, contatos
Descadastro e créditos	Registrar/remover opt-out; consultar saldo e consumo de créditos de IA
Documentação	Buscar na documentação oficial para responder dúvidas de uso

O que um agente não consegue fazer

Pagamentos e recarga de créditos, criar ou conectar conexões de WhatsApp, enviar mídia (só texto), editar papéis e permissões e alterar configurações gerais da empresa ficam de fora, de propósito. A lista completa está em O que ele não faz.

Requisitos

• Plano com MCP. O acesso MCP é um recurso do plano (veja os planos da Paralela). Sem ele, o endpoint responde 403 ("O acesso MCP não está incluído no plano desta empresa").
• Administrador para criar tokens. É necessária a permissão company_settings:manage.
• Um usuário com o acesso certo. O token herda as permissões do usuário; se quiser limitar o que o agente alcança, crie um usuário dedicado a ele.

Endpoint

POST /mcp

• Transporte: Streamable HTTP (Model Context Protocol).
• Modo: stateless — cada requisição é independente, sem sessão persistente entre chamadas.
• A URL completa é o endereço da API da sua conta seguido de /mcp (ex.: https://api.suaempresa.com/mcp). A janela de criação do token mostra o endereço exato.

Autenticação

Toda requisição precisa enviar um token MCP, de uma destas formas:

Authorization: Bearer mcp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

x-api-key: mcp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

POST /mcp/t/mcp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

A última forma, com o token na URL, existe para clientes que não deixam configurar cabeçalhos, como os conectores personalizados do claude.ai. Nesse caso a própria URL passa a ser a credencial: trate-a como uma senha.

O token é vinculado a um usuário e a uma empresa. O agente herda as permissões desse usuário — ele só consegue executar o que o usuário poderia executar na interface. Use um usuário com o nível de acesso adequado ao que o agente precisa fazer.

Respostas de erro de autenticação: 401 (token ausente, inválido ou desativado) e 403 (plano sem MCP).

Tokens MCP

Pela interface (recomendado)

Acesse API de Mensagens → Servidor MCP (IA). A seção Tokens MCP lista os tokens da empresa (nome, data de criação, último uso e situação) e permite:

• Criar um token: clique em Novo token, dê um nome que identifique onde ele será usado (ex.: "Claude Desktop do João") e confirme. O token aparece uma única vez, junto com a configuração pronta para colar no cliente de IA — copie os dois antes de fechar a janela.
• Revogar um token: clique no ícone de lixeira. Qualquer cliente que use aquele token perde o acesso imediatamente.

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

A seção só aparece para quem tem permissão de administrador (company_settings:manage).

Pela API

As mesmas operações estão disponíveis 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 é exibido apenas uma vez — guarde-o com segurança):

{
  "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 não 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, último 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 já monta esta configuração 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 cabeçalho de autorização 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 cabeçalho Authorization.

claude.ai (conector personalizado)

O claude.ai não permite configurar o cabeçalho Authorization. Em Personalizar → Conectores → Adicionar conector personalizado:

• Informe a URL com o token: https://api.suaempresa.com/mcp/t/mcp_SEU_TOKEN. A janela de criação do token já exibe essa URL pronta.
• Em Autenticação, escolha Sem login (No sign-in) e não preencha os campos de OAuth.

Se a sua organização no claude.ai tiver a seção Request headers, também dá para usar a URL /mcp e adicionar o cabeçalho x-api-key com o token.

Testando a conexão

Depois de conectar, peça ao agente algo de leitura, como "liste as filas da empresa" ou "quantos atendimentos abertos eu tenho?". Se ele responder com dados da sua empresa, a conexão e o token estão corretos. Um 401 indica token errado ou revogado; um 403, que o plano não inclui o MCP.

Permissões e segurança

• Respeita as permissões do usuário. O agente atua dentro do perfil do usuário dono do token; ações negadas por permissão continuam negadas pelo MCP, com a mensagem Permissão negada: esta ação requer "recurso:acao".
• Respeita o plano. Ferramentas de recursos que o plano da empresa não inclui (por exemplo, Flow Builder, campanhas ou integrações) nem aparecem na lista de ferramentas. Por isso empresas com planos diferentes podem ver conjuntos diferentes.
• Isolamento por empresa. O agente só enxerga e altera dados da empresa do token.
• Revogação imediata. Excluir o token bloqueia na hora qualquer cliente que o utilize.

Confirmação de ações sensíveis

A maioria das ferramentas que alteram dados (enviar mensagem, transferir, criar, editar, excluir, campanhas, ações em massa) exige confirmação em duas chamadas:

1. Na primeira chamada a ferramenta não executa. Ela responde CONFIRMAÇÃO NECESSÁRIA: <resumo do que será feito>.
2. O agente mostra o resumo ao usuário e espera o "sim".
3. Na chamada seguinte (uma nova requisição) a mesma ferramenta executa.

Detalhes que importam para quem integra:

• Cada requisição HTTP é uma "rodada" diferente: repetir a ferramenta na mesma requisição não confirma.
• A confirmação vale por 10 minutos e é associada ao token e à ferramenta. Passado esse prazo, a ferramenta volta a pedir confirmação.
• A segunda chamada executa com os parâmetros enviados nela: reenvie os mesmos da primeira.
• Consultas (list_*, get_*, show_*, search_*) e algumas ações simples (como add_tags_to_contact) nunca pedem confirmação.

Se o seu cliente não for uma pessoa conversando, trate o CONFIRMAÇÃO NECESSÁRIA como um ponto de aprovação: só reenvie a chamada depois de uma decisão explícita de quem opera.

Como o agente deve trabalhar

Para o agente acertar de primeira, estas orientações valem como regra (o Assistente Paralela já as segue):

• Descubra o id antes de agir. Use uma ferramenta list_* ou search_* (filas, tags, fluxos, contatos) em vez de adivinhar ids.
• Busque na documentação com search_docs antes de responder "como faço X".
• Fluxos novos nascem inativos. Depois de criar um fluxo, crie o gatilho por frase para ele disparar e ative-o quando estiver revisado.
• Busca de leads gasta créditos de IA (plan_lead_search, start_lead_search, e cada rodada de uma busca recorrente criada com create_lead_search_schedule ou retomada com toggle_lead_search_schedule). Consulte o saldo com get_ai_credits_balance e avise o usuário.
• Descadastro (opt-out): quem pediu para sair não recebe campanha nem prospecção. Remova um opt-out só se o usuário pedir.
• Prospecção recorrente (create_recurring_prospection): cada rodada cria uma prospecção nova e é pulada, com o motivo na lista (list_recurring_prospections), se a anterior ainda roda, se a conexão está fora do ar ou se não há ninguém para abordar; 3 falhas seguidas pausam a serie. Para repetir por comportamento use repeatMode: previous_outcome com behavior e afterDays.
• Prospecção em conexão oficial de WhatsApp exige modelo aprovado (list_whatsapp_templates); em QR Code vale texto livre.

Ferramentas por área

Os nomes abaixo são os que o cliente MCP enxerga. Para ver a descrição e os parâmetros de cada uma, liste as ferramentas no próprio cliente (tools/list); esta tabela é um mapa para localizar a área certa.

Área	Leitura (não altera nada)	Escrita (a maioria pede confirmação)
Atendimentos	list_tickets, show_ticket, get_ticket_conversation, get_ticket_logs, list_ticket_notes, list_ticket_views	send_ticket_message, transfer_ticket, update_ticket_status, create_ticket_note, delete_ticket_note, mark_ticket_unread, start_ticket_ai, stop_ticket_ai, start_ticket_flow, stop_ticket_flow, bulk_update_tickets
Contatos	search_contacts, show_contact, list_contact_custom_fields	create_contact, update_contact, block_unblock_contact, toggle_contact_bot, toggle_contact_accept_audio, update_contact_responsible, add_tags_to_contact, remove_tags_from_contact, bulk_add_tags_by_filter, bulk_update_responsible_by_filter, bulk_delete_contacts_by_filter
Descadastro	list_contact_opt_outs, get_opt_out_settings	register_contact_opt_out, remove_contact_opt_out
Campanhas	list_campaigns, show_campaign, get_campaign_report	create_campaign, update_campaign, copy_campaign, cancel_campaign, restart_campaign, resend_campaign, delete_campaign
Recorrentes e em massa	list_recurring_campaigns, list_bulk_actions, get_campaign_settings	create_recurring_campaign, toggle_recurring_campaign, execute_recurring_campaign, execute_bulk_action, update_campaign_settings
Prospecção e agenda	list_prospections, get_prospection_report, list_prospection_rules, list_recurring_prospections, list_schedules	create_prospection, cancel_prospection, restart_prospection, create_prospection_rule, delete_prospection_rule, create_recurring_prospection, toggle_recurring_prospection, create_schedule, update_schedule, delete_schedule
Busca de leads	list_lead_searches, get_lead_search, list_lead_candidates, list_lead_search_schedules	plan_lead_search, start_lead_search, cancel_lead_search, review_lead_candidates, import_lead_candidates, create_lead_prospection, create_lead_search_schedule, toggle_lead_search_schedule
Flow Builder	list_flows, get_flow, list_flow_versions, list_flow_templates, list_flow_categories, list_flow_triggers	create_flow, modify_flow, use_flow_template, duplicate_flow, rename_flow, toggle_active_flow, restore_flow_version, move_flow_to_category, create_flow_category, create_template_from_flow, delete_flow, create_flow_trigger, update_flow_trigger, toggle_flow_trigger, delete_flow_trigger
Agentes de IA	list_prompts, list_ai_agent_tools, list_ai_triggers, list_mcp_servers, list_voices	create_prompt, update_prompt, duplicate_prompt, delete_prompt, create_ai_agent_tool, test_ai_agent_tool, create_ai_trigger
Kanban e tarefas	list_kanban_boards, list_kanban_automations, list_loss_reasons, list_tasks, list_task_statuses, list_task_workspaces	move_kanban_card, create_loss_reason, create_task, update_task, update_task_status, delete_task
E-mail marketing	list_email_campaigns, get_email_campaign_stats, list_email_templates	create_email_campaign, cancel_email_campaign, create_email_template, update_email_template, delete_email_template, send_test_email
Loja	list_products, list_orders, show_order, list_neighborhoods	create_product, update_product, duplicate_product, delete_product, update_order_status, update_order_fulfillment_status, mark_order_paid, create_payment_link, send_payment_link
Conexões WhatsApp	list_whatsapp_connections, list_whatsapp_templates, list_whatsapp_notifications	restart_whatsapp_connection, sync_whatsapp_templates, send_whatsapp_notification
Formulários e webhooks	list_forms, list_leads, list_webhook_integrations	create_form, delete_form, convert_lead_to_contact, create_webhook_integration, test_webhook_integration, execute_webhook_integration
Cadastros	list_queues, list_tags, list_tag_categories, list_quick_messages, list_custom_field_definitions, list_users, list_roles, list_files, list_help_articles, list_announcements	create_, update_ e delete_ de queue, tag, tag_category, quick_message, custom_field_definition e user (ex.: create_queue)
Relatórios	get_tickets_stats, get_response_time_insights, get_attendant_performance, get_closure_reasons, get_contacts_report, get_contacts_by_tags, get_dashboard_configuration, list_dashboard_widgets, list_system_presets	create_dashboard_widget, delete_dashboard_widget
Créditos de IA	get_ai_credits_balance, list_ai_credits_usage	—
Documentação	search_docs	—

Diferença para a API de Mensagens

A API de Mensagens é ideal para integrações diretas e determinísticas (enviar uma mensagem, criar um lead, verificar um número) a partir de outro sistema. O servidor MCP é voltado para agentes de IA que decidem, em linguagem natural, quais ações executar — cobrindo um conjunto muito maior de operações da plataforma.

Preciso de...	Use
Disparar sempre a mesma chamada a partir do meu sistema (enviar mensagem, criar lead)	API de Mensagens
Deixar um agente de IA operar a plataforma em linguagem natural	Servidor MCP
Operar a plataforma sem sair do sistema, conversando	Assistente Paralela