# iClips — how to use (mcp.ai)

Advertising and marketing agency ERP and workflow on iClips (Public API v1). Read the full finance module (bank accounts, payables and receivables, invoices with withheld taxes), manage jobs, pieces, tasks and production checklists, and extract the entire project hierarchy with time entries per executor. Authenticated via API key (X-Api-Key) generated in the panel under Avatar, CHAVE DE API.

## Option A — via MCP (recommended)
Remote MCP endpoint (HTTP, streamable): `https://api.mcp.ai/p_iclips?ms=1788484500000`
Add it as a custom/remote MCP connector in your client (Claude, Cursor, VS Code…), then authenticate when prompted. Once connected, ask the agent to use the server's tools (e.g. `iclips_financial_accounts`).

## Option B — via direct REST API
Base URL: `https://api.mcp.ai/api/iclips`
Auth: `Authorization: Bearer sk_live_…` — create a workspace API key at https://mcp.ai/settings/api-keys
Discover endpoints: `GET https://api.mcp.ai/api/iclips/_endpoints`

### Endpoints
- `POST https://api.mcp.ai/api/iclips/financial/accounts` — Lista as contas bancárias ativas da agência no iClips (id, nome, isDefault, banco, agência e número da conta).
  - body: { account?: string }
- `POST https://api.mcp.ai/api/iclips/financial/entries/get` — Lê os lançamentos financeiros do iClips (entradas, saídas e o que está em aberto a pagar e a receber).
  - body: { from?: string, to?: string, date_field?: string, type?: string, account_id?: number, category_id?: number, dre_indicator?: string, destination_id?: number, job_id?: number, limit?: number, offset?: number, entry_ids?: number[], account?: string }
- `POST https://api.mcp.ai/api/iclips/financial/entries/list` — Lê os lançamentos financeiros do iClips (entradas, saídas e o que está em aberto a pagar e a receber).
  - body: { from?: string, to?: string, date_field?: string, type?: string, account_id?: number, category_id?: number, dre_indicator?: string, destination_id?: number, job_id?: number, limit?: number, offset?: number, entry_ids?: number[], account?: string }
- `POST https://api.mcp.ai/api/iclips/financial/invoices/get` — Lê as notas fiscais de serviço (NFS-e) emitidas pela agência no iClips.
  - body: { from?: string, to?: string, status?: string, limit?: number, offset?: number, invoice_ids?: number[], account?: string }
- `POST https://api.mcp.ai/api/iclips/financial/invoices/list` — Lê as notas fiscais de serviço (NFS-e) emitidas pela agência no iClips.
  - body: { from?: string, to?: string, status?: string, limit?: number, offset?: number, invoice_ids?: number[], account?: string }
- `POST https://api.mcp.ai/api/iclips/job/pieces/write/add` — Vincula uma peça do catálogo a um job existente, ou atualiza uma peça já vinculada a ele.
  - body: { job_id: number, job_piece_id?: number, data: string, account?: string, job_ids?: number[], job_piece_ids?: number[] }
- `POST https://api.mcp.ai/api/iclips/job/pieces/write/update` — Vincula uma peça do catálogo a um job existente, ou atualiza uma peça já vinculada a ele.
  - body: { job_id: number, job_piece_id?: number, data: string, account?: string, job_ids?: number[], job_piece_ids?: number[] }
- `POST https://api.mcp.ai/api/iclips/job/tasks/write/create` — Cria ou atualiza uma tarefa manual dentro de um job existente no iClips.
  - body: { job_id: number, task_id?: number, data: string, account?: string, job_ids?: number[], task_ids?: number[] }
- `POST https://api.mcp.ai/api/iclips/job/tasks/write/update` — Cria ou atualiza uma tarefa manual dentro de um job existente no iClips.
  - body: { job_id: number, task_id?: number, data: string, account?: string, job_ids?: number[], task_ids?: number[] }
- `POST https://api.mcp.ai/api/iclips/jobs/delete` — Exclui jobs (projetos) do iClips. É destrutivo e não tem desfazer pela API.
  - body: { job_ids: number[], account?: string }
- `POST https://api.mcp.ai/api/iclips/jobs/write/create` — Cria ou atualiza um job (projeto) no iClips.
  - body: { job_id?: number, data: string, account?: string, job_ids?: number[] }
- `POST https://api.mcp.ai/api/iclips/jobs/write/update` — Cria ou atualiza um job (projeto) no iClips.
  - body: { job_id?: number, data: string, account?: string, job_ids?: number[] }
- `POST https://api.mcp.ai/api/iclips/list/accounts` — Lista as agências iClips (chaves de API) ligadas a este install, com id, apelido e nome.
  - body: { account?: string }
- `POST https://api.mcp.ai/api/iclips/piece/categories/dropdown` — Lista as categorias de peça disponíveis na agência (id e nome).
  - body: { account?: string }
- `POST https://api.mcp.ai/api/iclips/piece/categories/list` — Lista as categorias de peça disponíveis na agência (id e nome).
  - body: { account?: string }
- `POST https://api.mcp.ai/api/iclips/pieces/delete` — Exclui peças do catálogo do iClips (o provider faz exclusão lógica).
  - body: { piece_ids: number[], account?: string }
- `POST https://api.mcp.ai/api/iclips/pieces/get` — Lê o catálogo de peças da agência no iClips.
  - body: { q?: string, categoria?: string, status?: string, basedOnTemplateId?: string, page?: number, pageSize?: number, piece_ids?: number[], account?: string }
- `POST https://api.mcp.ai/api/iclips/pieces/list` — Lê o catálogo de peças da agência no iClips.
  - body: { q?: string, categoria?: string, status?: string, basedOnTemplateId?: string, page?: number, pageSize?: number, piece_ids?: number[], account?: string }
- `POST https://api.mcp.ai/api/iclips/pieces/write/checklist` — Cria ou atualiza uma peça no catálogo do iClips, ou marca um item do checklist.
  - body: { piece_id?: number, data: string, account?: string, piece_ids?: number[] }
- `POST https://api.mcp.ai/api/iclips/pieces/write/create` — Cria ou atualiza uma peça no catálogo do iClips, ou marca um item do checklist.
  - body: { piece_id?: number, data: string, account?: string, piece_ids?: number[] }
- `POST https://api.mcp.ai/api/iclips/pieces/write/update` — Cria ou atualiza uma peça no catálogo do iClips, ou marca um item do checklist.
  - body: { piece_id?: number, data: string, account?: string, piece_ids?: number[] }
- `POST https://api.mcp.ai/api/iclips/projects/extract` — Extrai do iClips a hierarquia completa de projetos de um período: Jobs, Peças, Workflows, Atividades e Tarefas, até os apontamentos de hora.
  - body: { dataInicio: string, dataFim: string, idCliente?: number, idGrupoCliente?: number, page?: number, pageSize?: number, account?: string }
- `POST https://api.mcp.ai/api/iclips/workflow/templates/get` — Lê os modelos de workflow configurados na agência no iClips.
  - body: { template_ids?: number[], account?: string }
- `POST https://api.mcp.ai/api/iclips/workflow/templates/list` — Lê os modelos de workflow configurados na agência no iClips.
  - body: { template_ids?: number[], account?: string }

## Example prompts
- "How much does the agency have payable this month, and to which suppliers"
- "How many hours did each person log on client X's pieces in January"
- "Create a job for client 42 with the briefing and approval tasks"

## More
- Page: https://mcp.ai/iclips
- Agent spec (llms.txt): https://mcp.ai/iclips/llms.txt
- Postman collection: https://mcp.ai/iclips/postman.json