iClips MCP: conecte seu assistente de IA aos dados da agência
O iClips MCP (Model Context Protocol) é a ponte entre a base de dados do iClips e os ambientes de Inteligência Artificial que sua equipe já usa — Claude Desktop, Claude.ai, Cursor, Codex, plataformas de automação como o n8n ou qualquer ferramenta compatível com o protocolo MCP. Em vez de navegar por telas e relatórios, você pergunta em linguagem natural e recebe o dado operacional em tempo real, no ambiente onde já está trabalhando.
Mais do que consultar, a IA também executa: cadastra peças comerciais, abre jobs, atualiza tabelas de preço de veículo e cria contas no Financeiro — sempre dentro das permissões do usuário conectado.
Entenda o que é o iClips MCP
Um protocolo que dá à IA o contexto operacional da agência — com a permissão do usuário validada a cada instrução.
O protocolo MCP permite que a IA leia o contexto operacional, analise gargalos e execute cadastros comerciais sem que você precise sair da sua interface de trabalho ou da sua IDE. Na prática, ele funciona como um copiloto para diretores, gestores de tráfego, líderes de equipe e desenvolvedores.
Como a segurança funciona
A arquitetura opera com transporte Stateless (HTTP/SSE). A cada instrução enviada, a permissão do usuário é validada em tempo real contra os sistemas do iClips — ninguém acessa ou altera informações de squads ou agências fora do próprio escopo. Toda a execução de regras de negócio acontece de forma isolada no banco SQL Server da agência, sem qualquer compartilhamento de informação entre contas diferentes.
Conheça as ferramentas disponíveis
O MCP expõe um conjunto de ferramentas (tools) que vai de diagnóstico operacional a cadastro comercial, gestão de jobs, mídia e financeiro.
1. Leitura e diagnóstico de operações (squads)
- list_squads: identifica imediatamente os squads aos quais o usuário autenticado tem acesso.
- get_projects: consulta projetos ativos ordenados por nível de urgência, com a contagem exata de dias de atraso (SLAs).
- get_pieces: monitora peças em andamento no fluxo, identificando etapa atual do workflow, tempo de permanência e recursos emprestados (CrossSquadResource).
- get_squad_availability: visão detalhada de capacidade e horas alocadas por membro da equipe em determinada semana.
- get_rework_summary: identifica o acumulado de refações e aponta membros com taxa de retrabalho acima da média do squad.
- get_workflow_bottlenecks: mapeia gargalos operacionais e peças estagnadas na mesma etapa há 3 ou mais dias.
- get_squad_summary: painel executivo consolidado com o status de saúde do squad em tempo real —
healthy,attentionoucritical. - ping: utilitário de diagnóstico que confirma se a conexão com o servidor MCP está ativa.
2. Escrita e cadastro comercial de peças
- create_piece: cadastra novas peças comerciais, definindo valores base e tabelas sindicais (Sindrapro, Fenapro e Sindicato) divididos em Criação, Finalização e Adaptação.
- create_pieces_bulk: cria até 5.000 peças em uma única chamada, com controle de idempotência e validação automática de duplicatas — ideal para atualizar uma tabela de preços completa, como a tabela SINAPRO.
3. Gestão de jobs (projetos, peças e tarefas)
Diferente das ferramentas de leitura de squads, estas não têm escopo por squad: qualquer job da agência pode ser criado, vinculado ou atualizado pelo copiloto.
- create_job: cria um job do zero — cliente, status, datas, prioridade, verba — com a mesma paridade do endpoint público de criação. Pode já sair com peças do catálogo vinculadas, tarefas manuais, ou gerar tudo automaticamente a partir de um modelo de job.
- create_job_peca: vincula uma peça já cadastrada no catálogo a um job existente, com título, descrição e prioridade específicos daquele job.
- update_job_peca: atualiza título, descrição, formato, serviço ou prioridade de uma peça já vinculada a um job.
- create_job_tarefa: cria uma tarefa manual (sem peça associada) dentro de um job existente, com datas de início/fim e prioridade.
- update_job_tarefa: atualiza título, descrição, datas, prioridade ou ordem de exibição de uma tarefa já vinculada a um job.
4. Tabela de preço de veículo — TV e rádio
- list_fornecedores_veiculo: busca fornecedores marcados como veículo (emissoras de TV, por exemplo) pelo nome — resolve o nome no id usado pelas demais ferramentas desta seção.
- list_pracas: busca praças (cidades/regiões de veiculação) pelo nome, para filtrar tabelas específicas de uma praça.
- list_tabelas_preco_veiculo: lista as tabelas de preço cadastradas para um fornecedor numa mídia — a vigente de cada combinação praça/cliente e, opcionalmente, o histórico já arquivado.
- get_tabela_preco_veiculo_ativa: consulta a grade completa da tabela vigente de um fornecedor — programas, horários e valores por duração de inserção.
- cadastrar_tabela_preco_veiculo: cadastra uma nova tabela de preço (grade de programas × valores por duração). Se já existir uma tabela vigente para a mesma combinação, ela é arquivada automaticamente e substituída — a mesma ferramenta serve para inserir e para atualizar.
5. Mídia exterior — bi-semanas
- search_bi_semanas: busca por código as bi-semanas cadastradas, os períodos quinzenais usados para veiculação de mídia exterior.
- import_bi_semanas_bulk: importa bi-semanas em lote, substituindo o script SQL manual antes usado para esse cadastro.
6. Financeiro — contas e caixas
- create_cash_account: cria uma conta bancária (com banco, agência e conta) ou um caixa (sem banco) no módulo Financeiro, com saldo inicial, empresa vinculada e opção de defini-la como conta padrão.
- update_cash_account: edita nome, empresa, saldo inicial, dados bancários ou status (ativa/inativa) de uma conta ou caixa existente.
Entenda como a capacidade do squad é calculada
Saber a fórmula por trás do diagnóstico é o que permite confiar no alerta de sobrecarga — e agir sobre ele.
| Métrica / conceito | Origem e lógica de cálculo |
|---|---|
| Capacidade semanal nominal | Derivada da carga horária mensal do funcionário (padrão de 176h/mês), pela fórmula Capacidade Semanal = Horas Produtivas × (5,0 / 22,0). |
| Horas alocadas | Soma o tempo estimado de Atividades de Peças no workflow com as Tarefas de Job ativas no período. |
| Zonas de alerta | Disponível: alocação abaixo de 60%. Saudável: carga equilibrada. Em risco / sobrecarga: acima de 90%, gerando alertas de severidade alta (high). |
Escolha o método de autenticação
Dois caminhos, conforme a ferramenta que vai se conectar — um para assistentes de chat, outro para IDEs e automações.
- OAuth 2.1 com PKCE + DCR (Dynamic Client Registration): o método primário, ideal para assistentes de chat como Claude Desktop e Claude.ai. O conector faz o registro dinâmico e direciona o usuário para o login seguro do iClips v2.
- API Keys públicas (
iclips_sk_…): chaves geradas no painel da agência no iClips, indicadas para IDEs de desenvolvimento (Cursor, Codex, VS Code), scripts de automação, webhooks ou fluxos no n8n.
Conecte pelo Claude Desktop ou Claude.ai (OAuth)
O caminho para quem vai conversar com os dados da agência dentro de um assistente de chat.
- Esteja logado no seu iClips.
- Acesse o Claude e clique em Personalizar.
- Clique em Conectores e depois em Adicionar.
- Dê um nome ao conector e, no campo de URL do servidor MCP remoto, informe
https://public-api.iclips.com.br/mcp. - Clique em Continuar e depois em Adicionar.
- Clique em Vincular. Abre-se uma nova aba com a mensagem "Claude quer acessar a sua conta iClips" — clique em Autorizar.
- A conexão é concluída e você já pode fazer perguntas sobre o iClips no chat.
Conecte por IDEs e automações (API Key)
O caminho para Cursor, Codex, VS Code, webhooks e fluxos no n8n.
- Gere uma chave de API pública no painel da sua agência no iClips (formato
iclips_sk_…). - Configure o servidor MCP apontando para
https://public-api.iclips.com.br/mcp, informando a sua API Key nos headers de autenticação.
Paginação e o bypass de busca exata
Para manter a agilidade, o sistema exibe por padrão 5 itens por resposta, com limite de 50. Ao buscar por nomes exatos — de projetos, usuários ou IDs específicos — o sistema aplica o bypass: ignora os limites de paginação e entrega o dado profundo imediatamente. É a forma mais rápida de chegar a uma resposta pontual.
Saiba o que perguntar ao copiloto
A diferença entre um gadget e uma ferramenta de gestão está nas perguntas que você faz. Estas são as que mais rendem.
| O que perguntar | Informação obtida | Benefício para a gestão |
|---|---|---|
| "Como está o squad esta semana?" | Status consolidado e alertas de severidade (high, medium, low). | Identificar riscos antes que virem crise. |
| "Quais projetos estão atrasados?" | Projetos ordenados por urgência e dias de atraso. | Priorização e cumprimento de SLAs. |
| "Quais peças estão com problema?" | Peças paradas há 3+ dias ou com prazos vencidos. | Enxergar gargalos invisíveis no workflow diário. |
| "Quem pode absorver demanda?" | Zonas de capacidade: Disponível (<60%), Saudável ou Em risco (>90%). | Prevenção de burnout e melhor distribuição de carga. |
| "Como está o retrabalho?" | Refações internas e de clientes por membro, comparadas à média. | Controle de qualidade e identificação de falhas de briefing ou técnica. |
| "Cadastre a nova tabela do SINAPRO" | Criação e atualização em lote de até 5.000 peças comerciais. | Cadastro comercial automatizado, sem trabalho manual. |
| "Cria um job pra campanha X com essas peças e tarefas" | Novo projeto já com peças e tarefas vinculadas. | Abertura de job mais rápida no início de uma campanha. |
| "Qual é a tabela de preço vigente da [emissora] pra SP?" | Grade completa de programas, horários e valores por duração. | Consulta de grade e valores sem abrir a tela de cadastro. |
| "Cadastra a nova tabela de preço da [emissora]" | Grade de TV/rádio cadastrada ou atualizada, com a anterior arquivada. | Atualização sem digitar linha por linha na tela. |
| "Importa essas bi-semanas de outdoor" | Períodos quinzenais de mídia exterior cadastrados em lote. | Substitui o script SQL manual usado até então. |
| "Cria a conta do [banco] da Agência X" | Conta ou caixa criada no Financeiro, com banco/agência/conta. | Abertura de conta direto pelo chat. |
| "Inativa a conta Y" | Conta ou caixa existente inativada ou reativada. | Ajuste rápido de cadastro financeiro sem abrir o sistema. |
O que todo mundo pergunta antes de conectar a IA ao iClips
A IA consegue ver dados de outros squads ou de outras agências?
Não. A permissão do usuário é validada em tempo real a cada instrução, contra os sistemas do iClips. A execução acontece isolada no banco da própria agência — não há compartilhamento de informação entre contas diferentes.
Qual método de autenticação eu devo usar?
Use OAuth quando a conexão for por um assistente de chat (Claude Desktop,
Claude.ai) — o login é o seu próprio login do iClips v2. Use API Key
(iclips_sk_…) para IDEs como Cursor, Codex e VS Code, scripts, webhooks e
fluxos no n8n.
O MCP só consulta dados ou também cadastra?
Também cadastra. Além da leitura operacional, ele cria peças comerciais (inclusive em lote, até 5.000 por chamada), abre e atualiza jobs, peças e tarefas, cadastra tabelas de preço de veículo, importa bi-semanas de mídia exterior e cria ou edita contas e caixas no Financeiro.
Consigo configurar boleto ou juros pelo MCP?
Não. As ferramentas de Financeiro cadastram e editam a conta ou o caixa em si. Configuração de boleto, juros e vínculos com PJBank/TBanks continua nas telas do módulo Financeiro.
Pedi uma consulta e vieram poucos resultados. Por quê?
O padrão é exibir 5 itens por resposta, com limite de 50, para manter a agilidade. Quando você busca por um nome exato — de projeto, usuário ou ID —, o sistema aplica o bypass e ignora a paginação, entregando o dado completo.
Preciso ser desenvolvedor para usar?
Para o caminho OAuth no Claude, não: são poucos cliques e o login é o seu do iClips. Já a conexão via API Key em IDEs, scripts ou n8n pressupõe alguém confortável com configuração técnica — o mesmo perfil indicado para a API Pública.
Uma atualização de tabela de preço apaga a anterior?
Não apaga: ao cadastrar uma tabela para uma combinação que já tem vigente, a
anterior é arquivada automaticamente e substituída pela nova. O histórico
continua consultável pelo list_tabelas_preco_veiculo.
Ainda precisa de ajuda? Fale com a gente pelo suporte@iclips.com.br ou pelo chat da plataforma.