MCP ou API: como escolher a forma de conectar o iClips a outras ferramentas
Além das telas, o iClips tem duas formas de conversar com outras ferramentas: o iClips MCP, que conecta um assistente de IA (como o Claude) aos dados da agência, e a API Pública, que um desenvolvedor usa para integrar o iClips a outros sistemas. As duas usam o mesmo endereço e parte das mesmas funções, mas servem a públicos diferentes, usam chaves diferentes e enxergam os dados de forma diferente.
Entenda as três formas de usar o iClips
Tela, MCP e API levam aos mesmos dados — o que muda é quem faz o pedido e como.
Pense num restaurante. Usar a tela do iClips é entrar na cozinha e montar o prato com as próprias mãos: controle total, passo a passo. A API é o cardápio fixo: só dá para pedir exatamente o que está escrito, do jeito que está escrito, e normalmente quem faz o pedido é um programador. O MCP é entregar esse cardápio a um garçom atento (a IA): você diz o que quer, em português, e ele decide quais itens pedir e em que ordem.
| Perfil | Como usa o iClips | Precisa programar? |
|---|---|---|
| Usuário das telas | Clica, preenche e navega no próprio iClips. | Não |
| Usuário com copiloto (MCP) | Conversa em português com uma IA conectada ao iClips, que consulta e cadastra por ele. | Não |
| Integração via API | Um desenvolvedor escreve código que fala direto com o iClips, em geral para algo que roda sozinho, sem ninguém perguntando. | Sim |
Um canal não substitui o outro. A tela continua sendo a forma mais completa — cobre praticamente tudo, mas exige alguém clicando. O MCP é para perguntar e agir rápido sem programar. A API é para automações que rodam sem supervisão e para alimentar outros sistemas, como um BI.
Veja o que cada canal faz
Cada um cobre um conjunto diferente de funções — algumas existem nos dois.
Só pelo MCP
- Diagnóstico da operação: projetos atrasados por urgência, peças paradas, gargalos do fluxo, refações e disponibilidade da equipe na semana — da agência inteira, de um cliente, de uma pessoa ou de um squad.
- Cadastro em lote de peças: até 5.000 peças de uma vez, por exemplo para atualizar a tabela do SINAPRO.
- Mídia: cadastrar tabelas de preço de veículo (TV e rádio) e importar bi-semanas.
- Financeiro: criar e editar contas bancárias e caixas.
Só pela API
- Projetos: alterar os dados de um projeto e excluir um projeto.
- Catálogo de peças: editar e excluir peças do catálogo e marcar itens do checklist de produção.
- Financeiro (só leitura): consultar contas bancárias, lançamentos de entrada e saída e notas fiscais emitidas.
- Extração para BI: puxar a hierarquia completa (Projetos → Peças → Workflows → Atividades e Tarefas → Apontamentos de horas) de um período.
- Listas de apoio: categorias de peça, templates de workflow e departamentos.
Nos dois, cada um do seu jeito
- Criar um projeto.
- Cadastrar uma peça no catálogo.
- Vincular peças e criar tarefas num projeto, e alterar essas peças e tarefas.
A lista completa de ferramentas e permissões do MCP está em iClips MCP: conecte seu assistente de IA aos dados da agência. A lista de endpoints da API está em Integração com a API Pública de iClips.
Entenda o que cada um enxerga
É a diferença mais importante entre os dois: o MCP age como uma pessoa, a API age como a agência.
MCP: as permissões de quem está conectado
O MCP age em nome de um colaborador. A IA vê e faz exatamente o que essa pessoa veria e faria nas telas:
- Valem as permissões da aba Permissões do cadastro do colaborador. Quem não pode criar projeto na tela também não cria pelo MCP.
- Vale a regra de clientes restritos: projetos desses clientes só aparecem para quem é atendimento, auxiliar ou seguidor do cliente ou do projeto.
- Tudo o que a IA cadastra fica registrado em nome do colaborador conectado.
- Se a pessoa deixa de ser colaboradora da agência, o acesso pelo MCP cai na instrução seguinte.
API: os dados da agência inteira
A chave da API Pública identifica a agência, não uma pessoa. Quem usa essa chave acessa os dados de toda a agência pelas funções da API, sem passar pelas permissões de um colaborador nem pela regra de clientes restritos.
Use a chave certa
As duas chaves ficam na mesma janela, mas não são intercambiáveis.
No iClips, clique no seu avatar (botão de Conta e Ajuda, no canto inferior esquerdo) e em Chave de API. A janela tem duas partes:
| Chave da API Pública | Chave de API para MCP | |
|---|---|---|
| Onde fica | No topo da janela Chave de API | Em Chaves de API para MCP, logo abaixo |
| Quem vê ou cria | Só administradores | Cada colaborador cria as suas |
| De quem é | Da agência — uma chave para a agência | Pessoal — cada pessoa pode ter várias, uma por ferramenta |
| Formato e uso | Enviada no cabeçalho X-Api-Key | Começa com iclips_sk_ e é enviada como Authorization: Bearer iclips_sk_… |
| O que enxerga | Os dados da agência inteira | O que o colaborador que criou a chave pode ver |
| Para quê | Integrações, automações e BI feitos por um desenvolvedor | Conectar ao MCP ferramentas como Cursor, Codex, Antigravity e n8n |
A chave para MCP aparece uma única vez, no momento em que é criada — guarde-a num lugar seguro. Se perder ou desconfiar que vazou, revogue na mesma lista e crie outra. Já a chave da API Pública fica sempre visível para o administrador no topo da janela: é a única válida para a agência, e é ela que as integrações devem usar. Usar a chave da API Pública no MCP, ou a do MCP na API, resulta em erro de autenticação.
Escolha o caminho
A pergunta certa é: quem vai fazer o pedido — uma pessoa conversando ou um sistema rodando sozinho?
| Se você quer… | Use |
|---|---|
| Perguntar como está a operação ("quais projetos estão atrasados?", "a Ana tem tempo essa semana?") | MCP |
| Cadastrar ou ajustar algo rápido, conversando, sem abrir as telas | MCP |
| Que cada pessoa veja só o que pode ver nas telas | MCP |
| Alimentar um BI ou outro sistema com os dados da agência, de forma recorrente | API |
| Uma automação que roda sozinha, sempre do mesmo jeito, sem ninguém perguntando | API |
| Consultar lançamentos financeiros e notas fiscais por integração | API |
| Controle manual completo, passo a passo | Telas do iClips |
O que todo mundo pergunta sobre MCP e API
Preciso de um desenvolvedor para usar o MCP?
Não para o Claude Desktop ou o Claude.ai: são poucos cliques e o login é o seu do iClips. Para ferramentas que usam a chave para MCP (Cursor, Codex, Antigravity, n8n), ajuda ter alguém confortável com configuração técnica. Já a API sempre exige um desenvolvedor para escrever e manter a integração.
Por que não aparece a chave da API Pública para mim?
Porque ela só é exibida para administradores, e só em agências dos planos Pro e Enterprise: a chave dá acesso aos dados da agência inteira. Se você precisa dela para uma integração, peça a um administrador da sua agência. Para usar o MCP, você não precisa dela — crie a sua em Chaves de API para MCP.
Posso usar a chave da API Pública no MCP?
Não. Cada canal aceita só a sua chave: o MCP usa o login do iClips ou uma chave
iclips_sk_… criada em Chaves de API para MCP, e a API usa a chave da agência no
cabeçalho X-Api-Key. Trocar uma pela outra dá erro de autenticação.
A IA conectada pelo MCP vê os mesmos dados que a API?
Não necessariamente. O MCP vê o que o colaborador conectado pode ver nas telas, respeitando permissões e clientes restritos. A API vê os dados da agência inteira pelas funções que ela oferece. Por isso um mesmo pedido pode trazer menos resultados pelo MCP do que pela API.
Uma função que só existe na API vai chegar ao MCP?
Os dois canais evoluem em paralelo, e o que cada um oferece hoje está nos artigos de cada canal. Se você precisa de uma função num canal em que ela ainda não existe, conte para o nosso suporte o que quer fazer — esse retorno ajuda a priorizar.
Ainda precisa de ajuda? Fale com a gente pelo suporte@iclips.com.br ou pelo chat da plataforma.