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 em nome do usuário conectado, que fica registrado como autor de cada alteração.
Entenda o que é o iClips MCP
Um protocolo que dá à IA o contexto operacional da agência — com o acesso do usuário conferido 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, o acesso do usuário é conferido de novo, em tempo real, contra os sistemas do iClips.
- Agência: toda consulta e todo cadastro acontecem isolados no banco da própria agência — não há compartilhamento de informação entre contas diferentes. Se o usuário deixa de ser colaborador da agência, ou se a agência deixa os planos Pro e Enterprise, o acesso pelo MCP cai na instrução seguinte.
- Permissões: a IA age com as permissões do usuário conectado, as mesmas da aba Permissões do cadastro do colaborador. Quem não pode criar projeto na tela também não cria pelo MCP. A tabela no fim do passo 2 mostra o que cada ferramenta exige.
- Recorte das consultas: as ferramentas de diagnóstico (passo 2) não dependem de squad. Sem filtro, elas olham tudo o que o usuário pode ver na agência; o squad é só mais um recorte, ao lado de projeto, cliente e pessoa.
- Clientes restritos: projetos de cliente marcado como restrito só aparecem, e só podem ser alterados, por quem é atendimento, auxiliar ou seguidor do cliente, ou atendimento, auxiliar ou seguidor do projeto. É a mesma regra das telas do iClips.
- Autoria: todo cadastro feito pela IA fica registrado em nome do usuário conectado.
Conheça as ferramentas disponíveis
As ferramentas aparecem no Claude em português, com o módulo do iClips na frente do nome — Projetos, Cadastros, Mídia e Financeiro.
Na lista de ferramentas do conector (Claude → Configurações → Conectores → iClips), cada uma aparece com o nome em português e o módulo como prefixo, como Projetos · Criar projeto. O Claude separa as consultas, que só leem dados, das ações, que criam ou alteram algo no iClips. Ali você escolhe quais ações ele pode fazer sem pedir sua confirmação. Entre parênteses está o nome técnico, usado em automações e no n8n.
Projetos — diagnóstico da operação
Estas consultas respondem sobre a agência inteira — tudo o que você tem permissão para ver — e podem ser recortadas da forma que a pergunta pedir: por projeto, por cliente (sempre o cliente do projeto), por atendimento, por executor ou por squad. Não é preciso ter squads cadastrados para usar nenhuma delas.
Duas pessoas aparecem em cada projeto, e o copiloto distingue as duas. O atendimento é o responsável pelo projeto — "os projetos da Bia". O executor é quem está fazendo uma etapa do workflow ou uma tarefa agora — "o que está com a Ana". Toda resposta informa o recorte consultado, para você saber se o número é da agência, de um cliente ou de uma pessoa.
- Consultar projetos (
get_projects): projetos ativos ordenados por nível de urgência, com a contagem exata de dias de atraso e o atendimento de cada um. - Consultar peças em andamento (
get_pieces): etapa atual do workflow, há quantos dias a peça está nela, o atendimento do projeto e quem está executando a etapa. Sem filtro, mostra só as peças atrasadas ou paradas há 3 dias ou mais. - Gargalos do fluxo (
get_workflow_bottlenecks): etapas onde as peças estão estagnadas há 3 ou mais dias, com a peça mais antiga de cada etapa e com quem ela está parada. - Resumo de refações (
get_rework_summary): refações pedidas pelo cliente e internas, agrupadas por executor, por cliente, por projeto ou por etapa — com destaque para o que está acima de 1,5× a média do recorte. - Disponibilidade (
get_availability): capacidade, horas alocadas e horas livres de cada pessoa na semana, da mais livre para a mais ocupada. Serve para uma pessoa específica, para as pessoas de um squad ou para a agência inteira. - Resumo do squad (
get_squad_summary): para quem trabalha com squads, o painel consolidado de um squad na semana —healthy,attentionoucritical— com os alertas que explicam o status. - Listar meus squads (
list_squads): mostra os squads do usuário, para descobrir o número de um squad quando a pergunta for sobre ele.
Projetos — projetos, peças e tarefas
Assim como o diagnóstico, valem para a agência inteira: o copiloto pode criar, vincular ou atualizar qualquer projeto da agência que o usuário conectado tenha permissão para mexer, respeitando a regra de clientes restritos.
- Criar projeto (
create_project): cria um projeto 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. As peças pedidas se somam às que o modelo de job traz. - Vincular peça ao projeto (
create_job_peca): vincula uma peça já cadastrada no catálogo a um projeto existente, com título, descrição, prioridade e quantidade específicos daquele projeto. O mesmo modelo de peça pode ser vinculado várias vezes, como na tela.
Ao vincular peças, o MCP segue as mesmas regras da tela:
- Repetir a peça ou informar a quantidade: "cria 8 posts" gera 8 peças, cada uma com o seu fluxo de trabalho, suas datas e seu histórico. "Cria uma peça de 8 posts" gera 1 peça com quantidade 8 e um fluxo só. Sem indicação, a quantidade é 1.
- Contrato de Fee Mensal: se a peça estiver fora do pacote contratado, se o pacote do mês já tiver acabado ou se o contrato não estiver vigente, a peça não é criada de imediato. A IA mostra o mesmo aviso da tela e pergunta, peça por peça, se você quer incluí-la como item extra. O consumo do pacote conta peças, não a quantidade.
- Projeto finalizado não recebe peça nova.
- Categoria: a peça herda a categoria do modelo de peça.
- Alterar peça do projeto (
update_job_peca): atualiza título, descrição, formato, serviço ou prioridade de uma peça já vinculada. - Criar tarefa no projeto (
create_job_tarefa): cria uma tarefa manual (sem peça associada) com datas de início/fim e prioridade. - Alterar tarefa do projeto (
update_job_tarefa): atualiza título, descrição, datas, prioridade ou ordem de exibição de uma tarefa.
Cadastros
- Buscar clientes (
list_clientes): clientes ativos e grupos de cliente por sigla, nome ou CPF/CNPJ — usado para resolver o cliente antes de criar o projeto. - Buscar colaboradores (
list_funcionarios): colaboradores ativos por nome ou e-mail — usado para definir o atendimento do projeto. - Cadastrar peça (
create_piece): cadastra peças comerciais, com valores base e tabelas sindicais (Sindrapro, Fenapro e Sindicato) divididos em Criação, Finalização e Adaptação. - Cadastrar peças em lote (
create_pieces_bulk): cria até 5.000 peças numa ú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.
Mídia — bi-semanas
- Buscar 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. - Importar bi-semanas (
import_bi_semanas_bulk): importa bi-semanas em lote, substituindo o script SQL manual antes usado para esse cadastro.
Mídia — tabela de preço de veículo (TV e rádio)
- Buscar veículos (
list_fornecedores_veiculo): busca fornecedores marcados como veículo (emissoras de TV, por exemplo) pelo nome. - Buscar praças (
list_pracas): busca praças (cidades/regiões de veiculação) pelo nome, para filtrar tabelas de uma praça. - Listar tabelas de preço (
list_tabelas_preco_veiculo): tabelas cadastradas para um fornecedor numa mídia — a vigente de cada combinação praça/cliente e, opcionalmente, o histórico arquivado. - Consultar tabela de preço vigente (
get_tabela_preco_veiculo_ativa): grade completa da tabela vigente — programas, horários e valores por duração de inserção. - Cadastrar tabela de preço (
cadastrar_tabela_preco_veiculo): cadastra uma nova grade de programas × valores por duração. Se já existir uma tabela vigente para a mesma combinação, ela é arquivada e substituída — a mesma ferramenta serve para inserir e para atualizar.
Financeiro — contas e caixas
- Criar conta ou caixa (
create_cash_account): cria uma conta bancária (com banco, agência e conta) ou um caixa (sem banco), com saldo inicial, empresa vinculada e opção de defini-la como conta padrão. - Alterar conta ou caixa (
update_cash_account): edita nome, empresa, saldo inicial, dados bancários ou status (ativa/inativa).
Utilitário
- iClips · Testar conexão (
ping): confirma se a conexão com o servidor MCP está ativa.
Que permissão cada ferramenta exige
As permissões são as da aba Permissões no cadastro do colaborador. Administradores podem usar todas as ferramentas.
| Ferramenta | Permissão necessária |
|---|---|
| Consultar projetos, Consultar peças, Gargalos do fluxo, Resumo do squad | Projetos (leitura ou escrita) |
| Disponibilidade | Workload (leitura ou escrita) |
| Resumo de refações | Relatório de produtividade |
| Buscar clientes | Clientes (leitura) ou Projetos (escrita) |
| Buscar colaboradores | Colaboradores (leitura) ou Projetos (escrita) |
| Criar projeto, Vincular/Alterar peça do projeto | Projetos (escrita) |
| Criar/Alterar tarefa do projeto | Tarefa (escrita) |
| Cadastrar peça, Cadastrar peças em lote | Peças (escrita) |
| Buscar bi-semanas | Mídias (leitura ou escrita) |
| Importar bi-semanas | Mídias (escrita) |
| Criar/Alterar conta ou caixa | Cadastros do Financeiro (escrita) |
Quando falta a permissão, a IA responde com o motivo, por exemplo "Você não tem permissão para criar projetos no iClips.", e não executa nada.
No Resumo do squad, a ocupação da equipe e o retrabalho do mês só aparecem para quem também tem as permissões de Workload e de Relatório de produtividade. Sem elas, o resumo continua disponível, mas esses dois números vêm em branco — não como zero.
Entenda como a disponibilidade é calculada
Saber a fórmula por trás do diagnóstico é o que permite confiar no alerta de sobrecarga — e agir sobre ele.
O cálculo é feito por pessoa, com ou sem squad: consultar a Ana, as pessoas de um squad ou a agência inteira usa sempre a mesma fórmula.
| 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. Depois de autorizar, a sessão se renova sozinha — não é preciso autorizar de novo a cada dia — e o acesso cai automaticamente se o usuário deixar de ser colaborador da agência.
- API Keys públicas (
iclips_sk_…): chaves pessoais, indicadas para IDEs de desenvolvimento (Cursor, Codex, VS Code), scripts de automação, webhooks ou fluxos no n8n.
Os dois métodos podem ser usados ao mesmo tempo pelo mesmo usuário, sem conflito. Em ambos, só colaboradores da agência têm acesso — contatos de cliente (usuários do iFlow) não conseguem autorizar o MCP.
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 — na tela de login, informe o domínio da agência em que você quer usar o MCP.
- 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, Antigravity, VS Code, webhooks e fluxos no n8n.
-
No iClips, clique no seu avatar e em Chave de API. Na janela que abre, vá em Chaves de API para MCP e clique em Nova chave (formato
iclips_sk_…). A chave é pessoal: cada pessoa gera a sua — tudo o que for feito com ela fica registrado em nome de quem a gerou.A chave aparece uma única vez, no momento em que é criada: copie, marque Copiei a chave e guarde num lugar seguro. Para cancelar uma chave perdida ou que deixou de ser usada, clique em Revogar na mesma lista.
-
Configure o servidor MCP apontando para
https://public-api.iclips.com.br/mcp, enviando a chave no headerAuthorization: Bearer iclips_sk_….
Exemplo para o Claude Desktop (claude_desktop_config.json) ou qualquer cliente que use o mcp-remote:
{
"mcpServers": {
"iclips": {
"command": "npx",
"args": [
"mcp-remote",
"https://public-api.iclips.com.br/mcp",
"--header",
"Authorization:Bearer ${ICLIPS_API_KEY}"
],
"env": { "ICLIPS_API_KEY": "iclips_sk_..." }
}
}
}
Antigravity (Gemini)
O Antigravity, editor do Google que usa o Gemini, se conecta direto ao servidor remoto, sem o mcp-remote. Abra Manage MCP servers → View raw config e adicione o iClips ao arquivo mcp_config.json. Nele, o endereço vai no campo serverUrl — o Antigravity não aceita url:
{
"mcpServers": {
"iclips": {
"serverUrl": "https://public-api.iclips.com.br/mcp",
"headers": {
"Authorization": "Bearer iclips_sk_..."
}
}
}
}
Paginação e busca de um projeto específico
Para manter a agilidade, o sistema exibe por padrão 5 itens por resposta (10 pessoas na disponibilidade), com limite de 50 e paginação pelo parâmetro offset. Ao buscar um projeto pelo nome ou pelo número, a consulta devolve todos os resultados encontrados, até 50 — é 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 |
|---|---|---|
| "Quais projetos estão atrasados?" | Projetos da agência ordenados por urgência e dias de atraso. | Priorização e cumprimento de SLAs. |
| "Como estão os projetos do cliente Loggia?" | Projetos e peças só daquele cliente, com atendimento e executores. | Responder ao cliente com dado atual, sem montar relatório. |
| "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. |
| "O que está com a Ana agora?" | Peças cuja etapa atual está com ela. | Saber o que redistribuir antes de uma ausência ou de um pico. |
| "A Ana tem tempo essa semana?" | Horas livres e zona: Disponível (<60%), Saudável ou Em risco (>90%). | Prevenção de burnout e melhor distribuição de carga. |
| "Qual cliente mais pediu refação no mês?" | Refações por cliente, separando as pedidas pelo cliente das internas. | Rever briefing e escopo com quem mais gera retrabalho. |
| "Como está o retrabalho da equipe?" | Refações por executor, comparadas à média. | Controle de qualidade e identificação de falhas de briefing ou técnica. |
| "Como está o squad de Mídia esta semana?" | Status consolidado do squad e alertas de severidade (high, medium, low). | Identificar riscos antes que virem crise. |
| "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. |
| "No projeto Planejamento Março da ABC, cria 8 posts e 4 newsletters" | 12 peças no projeto, uma por item, cada uma com o seu fluxo de trabalho. | Planejamento mensal aberto pelo chat, com o Fee Mensal conferido peça por peça. |
| "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 outras agências?
Não: a execução acontece isolada no banco da própria agência, sem compartilhamento entre contas. Dentro da agência, a IA vê o mesmo que você veria nas telas do iClips — as suas permissões e a regra de clientes restritos valem tanto para as consultas quanto para os cadastros.
Minha agência não usa squads. O diagnóstico funciona?
Funciona. As consultas olham a agência inteira e podem ser recortadas por projeto, cliente, atendimento ou pessoa — o squad é só mais uma opção de recorte. Pergunte direto, por exemplo "quais projetos do cliente X estão atrasados?" ou "a Ana tem tempo essa semana?".
Posso consultar um squad do qual não faço parte?
Pode, desde que você tenha a permissão de Projetos no iClips — a mesma regra das telas. O resumo mostra a ocupação e o retrabalho do squad só se você também tiver as permissões de Workload e de Relatório de produtividade.
A IA respondeu que o MCP é exclusivo dos planos Pro e Enterprise. O que faço?
A sua agência não está num desses planos, e por isso o acesso ao MCP é recusado, tanto pelo Claude (OAuth) quanto pelas chaves para MCP. Não adianta reconectar nem gerar uma chave nova: fale com o nosso time de CS para fazer o upgrade. Com o plano liberado, as chaves e a conexão do Claude voltam a funcionar.
A IA respondeu que eu não tenho permissão. O que faço?
A IA usa as mesmas permissões que você tem no iClips. Peça a um administrador para liberar a permissão indicada na mensagem no seu cadastro de colaborador, na aba Permissões. A mudança vale já na próxima instrução, sem precisar reconectar a IA nem gerar uma chave nova.
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.
A IA perguntou se a peça entra como item extra. Por quê?
O projeto tem um contrato de Fee Mensal e a peça está fora do pacote, o pacote do mês acabou ou o contrato não está vigente. É o mesmo aviso que a tela mostra. Confirme para incluir a peça como item extra, ou responda que não para deixá-la de fora. A IA pergunta peça por peça, e nada entra sem a sua confirmação.
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. Peça "mostre mais" ou "os próximos" e a IA busca a página seguinte. Quando você busca um projeto pelo nome ou número, vêm todos os resultados encontrados, até 50.
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.
Preciso autorizar o Claude de novo todo dia?
Não. Depois da primeira autorização, a sessão se renova sozinha em segundo plano. Você só precisa autorizar de novo se remover o conector, se ficar muito tempo sem usar ou se o seu acesso à agência mudar.
Funciona com o Gemini?
Funciona pelo Antigravity, o editor do Google que usa o Gemini: gere uma chave em Chaves de API para MCP e siga a configuração do passo 6. No app de chat do Gemini (gemini.google.com), conectar um servidor personalizado depende do plano contratado com o Google e, nas empresas, de liberação do administrador do Google Workspace. Se você usar o iClips MCP com o Gemini, conte para o nosso suporte como foi.
Posso usar OAuth e API Key ao mesmo tempo?
Pode. São credenciais independentes: criar uma chave não desconecta o Claude, e autorizar o Claude não revoga a chave. Só evite cadastrar o mesmo servidor duas vezes no mesmo assistente — as ferramentas aparecem duplicadas.
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 pela ferramenta Mídia · Listar tabelas de preço.
Ainda precisa de ajuda? Fale com a gente pelo suporte@iclips.com.br ou pelo chat da plataforma.