Pular para o conteúdo

Primeiros passos com agentes de codificação de IA

O jeito mais rápido de se conectar é dentro do próprio PlaidCloud: abra o menu do avatar (usuário) e escolha Conecte sua IA, selecione o cliente que você usa e siga as etapas exibidas — incluindo a URL do servidor MCP do seu espaço de trabalho, já preenchida. Ele fica disponível sempre que o seu espaço de trabalho tem o direito de uso de IA ativado. O restante desta página, e as páginas por cliente que vêm depois dela, continuam sendo a referência — continue a leitura se você não está na interface web ou quer ter o quadro completo da autenticação e do que o servidor expõe.

O Model Context Protocol é um padrão aberto para permitir que agentes de IA conversem com ferramentas e dados externos. O PlaidCloud executa um servidor MCP em todos os espaços de trabalho que encapsula os mesmos auxiliares centrais usados pela API REST — agrupados por intenção (find, describe, upsert, run, organize) para que um agente possa navegar pela superfície sem carregar mais de 1.000 nomes de métodos RPC de baixo nível.

O servidor fica em:

https://<your-workspace>.plaid.cloud/mcp

Substitua <your-workspace> pelo subdomínio do seu espaço de trabalho (o que você usa para entrar na interface do PlaidCloud).

O catálogo cobre a maior parte da superfície do dia a dia de que um agente precisa:

  • Projetos, fluxos de trabalho, etapas — find/describe/upsert/run/organize, incluindo nova execução no nível da etapa e histórico de versões.
  • Tabelas, visões, consultas — introspecção de esquema, execução de consultas, exportações, instantâneos, branches. As visões são as mesmas que você vê no PlaidCloud, quer você as tenha criado no explorador de tabelas, quer um fluxo de trabalho as tenha criado.
  • Dimensões — describe, find, upsert, versão, gerenciamento de nós/aliases/propriedades.
  • Conexões — find/upsert/test de conexões com sistemas externos.
  • Lakehouse — branches, instantâneos, operações de optimize/vacuum.
  • Identidade — membros, grupos, sessões, listas de distribuição.
  • Documentos, painéis, UDFs, editores, agentes, publicações — ferramentas específicas de cada domínio.
  • Migração de fluxos de trabalho — converta exportações do Alteryx (alteryx_convert), KNIME (knime_convert), Prophecy (prophecy_convert) e Savant (savant_convert) preparadas em Documentos em fluxos de trabalho do PlaidCloud e coordene o trabalho de migração do portfólio.
  • Documentação do PlaidCloud — docs_search encontra páginas na documentação do PlaidCloud por palavra-chave, e docs_fetch lê uma página por completo, para que seu agente possa conferir como um recurso funciona antes de criar algo com ele.
  • Logs de fluxos de trabalho e acompanhamento de execuções — workflow_logs, workflow_run_status, workflow_job_track.

Toda ferramenta retorna um envelope uniforme {ok, data, next_cursor?, total?}; as falhas usam {ok: false, error: {code, retryable, message, hint?}}. As mutações aceitam dry_run=True para validação de planejamento sem gravação.

Os resultados das ferramentas são o maior consumidor individual do contexto de um agente, então as ferramentas find e describe retornam por padrão uma fatia modesta e permitem que você a amplie:

  • Linhas. Um find retorna 25 correspondências por página (step_find retorna 50). Uma página limitada define next_cursor, e as ferramentas find ainda nomeiam a lista cortada em truncated — qualquer um dos dois significa “há mais”, não “isso é tudo”. total sempre informa a contagem completa. Aumente limit ou percorra as páginas com o cursor.
  • Colunas. Passe fields=['id', 'name', 'update_time'] para receber somente essas colunas. Um nome de campo que não aparece em nenhum registro é um erro que lista os campos disponíveis, não uma omissão silenciosa — assim um erro de digitação falha de forma evidente em vez de retornar silenciosamente menos do que você pediu. As ferramentas que oferecem conjuntos curados também aceitam field_set='minimal' | 'default' | 'full'; chame mcp_introspect para ver quais parâmetros uma determinada ferramenta aceita.
  • Contagens. count_only=True dimensiona um conjunto de resultados sem buscá-lo.

O spec que uma ferramenta recebe, como o de project_upsert ou workflow_upsert, aceita somente os campos que ela lista. Um campo que ela não reconhece é recusado com um erro que cita o campo, em vez de ser ignorado e deixar você descobrir depois que ele não fez nada. Corrija o nome e envie a solicitação novamente. workflow_upsert recebe a descrição de um fluxo de trabalho como memo e aceita description como outro nome para ela.

mcp_batch agrupa várias chamadas de ferramentas em uma única solicitação. Ele aceita no máximo 100 chamadas, executa um número limitado delas por vez e não pode ser aninhado dentro de outro mcp_batch nem de uma receita — liste as chamadas em um único lote plano, o que não custa mais para enviar. Um lote acima do limite é recusado com uma mensagem que o cita, em vez de ser silenciosamente cortado; o limite restringe o trabalho que uma única solicitação pode iniciar, não o total que você pode fazer, então divida um trabalho maior em vários lotes.

A receita paginate_through_listing para após 200 páginas, por mais alto que seja o max_pages que você passar, e informa partial: true quando para antes. Entre isso e o limite de max_items, uma única chamada de paginação sempre termina.

Uma receita recusa uma chave de params que ela não reconhece, e a mensagem lista as chaves que aquela receita aceita — assim um parâmetro opcional digitado errado falha de forma evidente em vez de ser descartado, o que faria a chamada responder silenciosamente a uma pergunta diferente da que você fez. Chame mcp_recipes(name=...) para ver as chaves que uma determinada receita recebe.

Um resultado grande cujas linhas têm todas os mesmos campos volta orientado a colunas, em vez de como uma lista de objetos, de modo que os nomes dos campos são enviados uma vez, e não uma vez por linha:

{"_fmt": "cols", "cols": ["id", "name"], "rows": [["a1", "Sales"], ["b2", "Costs"]]}

A linha i é dict(zip(cols, rows[i])). Resultados pequenos, e qualquer resultado cujas linhas não compartilhem um conjunto idêntico de campos, continuam como matrizes comuns de objetos — então os dois formatos aparecem, e o código que lê essas respostas diretamente deve tratar cada um. O envelope ao redor não muda, e nenhum valor é convertido ou arredondado no caminho. Os agentes são informados sobre esse formato quando se conectam e o leem sem nenhuma orientação sua; a economia é de cerca de 30% dos caracteres e de cerca de 15% do orçamento de leitura de um agente em um tráfego típico de listagens, o que é contexto sobrando para a sua pergunta de verdade. (Os dois números diferem porque nomes de campo repetidos são baratos para um modelo ler — a economia de caracteres é sempre a maior das duas.)

Para ver o catálogo ativo, aponte seu agente para o servidor e chame mcp_introspect (sem argumentos) — ele retorna a contagem atual de ferramentas, resumos por domínio e assinaturas de parâmetros. Use mcp_recipes para ver roteiros comuns com várias ferramentas (paginar listas grandes, tirar instantâneo e depois modificar, executar novamente uma etapa com falha etc.).

Toda ferramenta upsert que define rótulos, para tabelas, fluxos de trabalho, etapas, projetos, dimensões, visões, editores, UDFs, conexões e warehouses, recebe dois parâmetros: labels adiciona rótulos e remove_labels os remove. Os outros rótulos do objeto permanecem. As remoções são aplicadas antes das adições, então uma única chamada pode renomear um rótulo:

{"remove_labels": ["01"], "labels": ["001"]}

Remover um rótulo que o objeto não tem não faz nada.

As ferramentas de visão funcionam com as visões que você vê no PlaidCloud:

  • view_find lista visões, e view_describe retorna uma pelo ID ou nome.
  • view_upsert cria uma visão ou atualiza uma no próprio local. Uma atualização mantém o ID e os rótulos da visão, e você pode alterar somente os rótulos sem enviar a consulta novamente.
  • view_organize exclui, renomeia, duplica e move visões.
  • Escreva os parâmetros de consulta como marcadores %(name)s.

As visões compartilham a árvore de pastas das tabelas, então use table_organize para gerenciar as pastas delas.

Criar fluxos de trabalho a partir de etapas nativas

Seção intitulada “Criar fluxos de trabalho a partir de etapas nativas”

Depois que seus dados estão no PlaidCloud, seu agente é orientado a criar cada transformação a partir de etapas nativas de tabela — as etapas Table Extract, as de junção, Table Melt, Table Union All e Table Lookup — em vez de usar a etapa Extrair SQL. Uma etapa nativa substitui as suas variáveis nos filtros e nas expressões, e o PlaidCloud gera o SQL dela para o warehouse do seu projeto. Uma etapa Extrair SQL envia a consulta ao warehouse exatamente como foi escrita: ela não substitui nenhuma variável, e o SQL é escrito para um único warehouse.

Seu agente pode testar uma configuração de Table Extract com query_run(mode='config') — a configuração que ele salvaria com step_upsert — e ver as linhas dela antes de salvar a etapa. Quando ele salva uma etapa Extrair SQL, step_upsert retorna uma entrada prefer_native_steps em config_warnings que nomeia as etapas nativas a usar no lugar, e describe_step_operation traz a mesma observação. A etapa Extrair SQL continua disponível para o que nenhuma etapa nativa consegue expressar.

O servidor traz um pequeno conjunto de iniciadores para as tarefas que as pessoas pedem pelo nome. Um cliente que oferece suporte a prompts MCP os lista e os oferece como um menu — consulte a documentação do seu cliente para saber onde ele os coloca — para que você escolha a tarefa em vez de descrever a sequência de chamadas de ferramentas que ela exige:

Iniciador O que você fornece
Importar um arquivo CSV para uma tabela O arquivo e, opcionalmente, o projeto, a pasta que o contém e um nome para a nova tabela
Explicar uma mudança de custo A tabela de resultados e, opcionalmente, o projeto e os dois períodos
Depurar um fluxo de trabalho com falha O fluxo de trabalho e, opcionalmente, o projeto
Explorar os dados do projeto O que você está procurando e, opcionalmente, o projeto

Cada um é uma mensagem inicial, não um comando: seu agente a lê e depois conduz as ferramentas por conta própria, então você pode editá-la ou continuar a conversa a partir dela.

Importar um arquivo sem conhecer o modelo de objetos

Seção intitulada “Importar um arquivo sem conhecer o modelo de objetos”

O iniciador de importação é o que mais poupa trabalho, porque o caminho ingênuo exige quatro ferramentas na ordem certa — encontrar a conta de documentos, navegar até o arquivo, criar a tabela de destino e então executar a importação — e um palpite errado em qualquer uma delas encerra o fluxo várias chamadas depois.

Ele lê texto delimitado — CSV, TSV e semelhantes. Uma pasta de trabalho do Excel ou um arquivo Parquet é rejeitado em vez de lido incorretamente; traga esses arquivos usando a etapa de importação correspondente em um fluxo de trabalho.

Em vez disso, o roteiro bulk_import_csv recebe a conta pelo nome e o arquivo pelo nome ou caminho:

mcp_recipe_run(name='bulk_import_csv', params={
'project_id': '<project>',
'document_path': 'sales_2026.csv',
'document_account': 'Demo Data',
})

Ele resolve a conta para o seu identificador, localiza o arquivo, cria a tabela com as colunas e os tipos lidos do próprio arquivo e a carrega — então você não informa nem um id de conta nem uma especificação de colunas. table_name assume por padrão o nome do arquivo sem a extensão, e table_path a raiz do projeto.

Informe a pasta quando a souber — 'document_path': 'raw/sales_2026.csv' — e a busca fica restrita a ela. Um arquivo citado em uma pasta só é correspondido nessa pasta: um arquivo de mesmo nome mais abaixo é oferecido como opção em vez de ser importado no lugar dele.

Quando um argumento é ambíguo, o resultado pergunta em vez de adivinhar:

{
"needs_choice": "document_account",
"question": "More than one document account is named 'Archive'. Which one?",
"candidates": [{"id": "...", "name": "Archive"}, {"id": "...", "name": "Archive"}]
}

Mostre os candidatos à pessoa que você está ajudando e chame o roteiro novamente com a resposta dela, devolvendo o candidato exatamente como foi fornecido. Quando o arquivo não é encontrado, a resposta lista os nomes mais próximos e informa quantos arquivos pesquisou, de modo que “não está lá” possa ser distinguido de “não está onde procurei”.

O servidor MCP do PlaidCloud aceita dois caminhos de autenticação:

  1. OAuth 2.1 + PKCE por meio de Dynamic Client Registration (DCR). É o que a interface de conector personalizado do Claude.ai usa, e também o padrão da ponte MCP do Claude Code. O cliente se registra e redireciona você para o login do Keycloak do PlaidCloud. Depois que você entra, o PlaidCloud mostra uma página Application Access Request que cita o aplicativo e a URI de redirecionamento para a qual enviará as credenciais — aprove-a uma vez por autorização para obter seu token. Isso é um controle de segurança, não uma formalidade: confira se o nome do aplicativo e a URI de redirecionamento correspondem ao cliente que você realmente está conectando e não aprove uma solicitação que você não iniciou.
  2. Token de portador estático em um cabeçalho Authorization. Para ambientes de execução de agentes que não têm um redirecionamento de navegador utilizável ou que querem um token de longa duração em um arquivo de configuração. O PlaidCloud expõe uma página auxiliar para gerar um para você (veja abaixo).

Abra esta URL em uma guia do navegador na qual você já esteja conectado ao PlaidCloud:

https://<your-workspace>.plaid.cloud/mcp/setup/token

A página retorna um trecho JSON pronto para colar na configuração MCP do seu agente. Cada espaço de trabalho tem seu próprio trecho.

A duração do token é regida pela política de duração do token de acesso do seu realm do Keycloak (normalmente de algumas horas a um dia). Para renová-lo, recarregue a mesma URL — a sessão do seu navegador gera o token novamente de forma automática.

O restante desta seção apresenta a configuração para clientes de agentes de IA específicos:

  • Claude Code — o agente de codificação da Anthropic (CLI, extensão do VSCode, plug-in do JetBrains).
  • Claude Desktop e Claude.ai — o aplicativo Claude para o consumidor (desktop) e a web (claude.ai) usando “Conectores personalizados”.
  • Cursor — o editor de código nativo de IA.
  • GitHub Copilot — o modo agente do Copilot no VSCode.
  • Google Gemini CLI — gemini-cli e Gemini Code Assist.
  • ChatGPT — status atual do suporte e solução alternativa recomendada.
  • Grok — conectar os conectores personalizados do Grok.
  • Solução de problemas — erros comuns e como corrigi-los.