Primeiros passos com agentes de programação com IA

A forma mais rápida de estabelecer ligação é no próprio PlaidCloud: clique em Ligue a sua IA na barra de ferramentas do cabeçalho, imediatamente à esquerda do interruptor de tema claro/escuro, escolha o cliente que utiliza e siga os passos apresentados — incluindo o URL do servidor MCP da sua área de trabalho, já preenchido. Está disponível sempre que a sua área de trabalho tenha o direito de utilização de IA ativado. O restante desta página, e as páginas por cliente que se lhe seguem, continuam a ser a referência — continue a ler se não estiver na interface web ou se pretender uma visão completa da autenticação e do que o servidor expõe.

O que é o servidor MCP?

O Model Context Protocol é uma norma aberta que permite aos agentes de IA comunicar com ferramentas e dados externos. O PlaidCloud executa um servidor MCP em cada área de trabalho, que encapsula as mesmas funções centrais que a API REST utiliza — agrupadas por intenção (find, describe, upsert, run, organize), para que um agente possa navegar na superfície sem carregar mais de 1000 nomes de métodos RPC de baixo nível.

O servidor está em:

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

Substitua <your-workspace> pelo subdomínio da sua área de trabalho (aquele que utiliza para iniciar sessão na interface do PlaidCloud).

O que expõe

O catálogo abrange a maior parte da superfície diária de que um agente necessita:

• Projetos, fluxos de trabalho, passos — find/describe/upsert/run/organize, incluindo a reexecução ao nível do passo e o histórico de versões.
• Tabelas, vistas, consultas — introspeção de esquemas, execução de consultas, exportações, instantâneos, ramos. As vistas são as mesmas que vê no PlaidCloud, quer as tenha criado no explorador de tabelas, quer tenham sido criadas por um fluxo de trabalho.
• Dimensões — describe, find, upsert, versões, gestão de nós/aliases/propriedades.
• Ligações — find/upsert/test de ligações a sistemas externos.
• Lakehouse — ramos, instantâneos, operações de optimize/vacuum.
• Identidade — membros, grupos, sessões, listas de distribuição.
• Documentos, painéis de controlo, 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 de portefólio.
• Documentação do PlaidCloud — docs_search encontra páginas da documentação do PlaidCloud por palavra-chave e docs_fetch lê uma página na íntegra, para que o seu agente possa verificar como funciona uma funcionalidade antes de construir com ela.
• Registos de fluxos de trabalho e acompanhamento de execuções — workflow_logs, workflow_run_status, workflow_job_track.

Cada ferramenta devolve um envelope uniforme {ok, data, next_cursor?, total?}; as falhas utilizam {ok: false, error: {code, retryable, message, hint?}}. As mutações aceitam dry_run=True para validação do plano sem escrita.

Manter os resultados pequenos

Os resultados das ferramentas são o maior consumidor individual do contexto de um agente, pelo que as ferramentas find e describe devolvem por predefinição uma fatia modesta e permitem alargá-la:

• Linhas. Uma pesquisa find devolve 25 correspondências por página (step_find devolve 50). Uma página limitada define next_cursor e, além disso, as ferramentas find indicam a lista truncada em truncated — qualquer um dos dois significa “há mais”, não “são todos”. total indica sempre a contagem completa. Aumente limit ou pagine com o cursor.
• Colunas. Indique fields=['id', 'name', 'update_time'] para obter apenas essas colunas. Um nome de campo que não existe em nenhum registo é um erro que lista os campos disponíveis, e não uma omissão silenciosa — assim, uma gralha falha de forma evidente em vez de devolver discretamente menos do que pediu. As ferramentas que oferecem conjuntos predefinidos aceitam também field_set='minimal' | 'default' | 'full'; chame mcp_introspect para ver os parâmetros que cada ferramenta aceita.
• Contagens. count_only=True dimensiona um conjunto de resultados sem o obter.

Agrupar pedidos em lote

mcp_batch agrupa várias chamadas de ferramentas num único pedido. Aceita no máximo 100 chamadas, executa em simultâneo um número limitado delas e não pode ser aninhado dentro de outro mcp_batch nem de uma receita — indique as chamadas num único lote simples, o que não custa mais a enviar. Um lote acima do limite é recusado com uma mensagem que o indica, em vez de ser silenciosamente truncado; o limite restringe o trabalho que um único pedido pode iniciar, não o total que pode fazer, pelo que deve dividir uma tarefa maior por vários lotes.

A receita paginate_through_listing pára após 200 páginas, independentemente do valor de max_pages que indicar, e comunica partial: true quando pára antes do fim. Entre este limite e o limite max_items, uma única chamada de paginação termina sempre.

Uma receita recusa uma chave de params que não reconhece e a mensagem lista as chaves que essa receita aceita — assim, um parâmetro opcional mal escrito falha de forma evidente em vez de ser ignorado, o que levaria a chamada a responder discretamente a uma pergunta diferente da que fez. Chame mcp_recipes(name=...) para saber as chaves que uma determinada receita aceita.

Resultados orientados a colunas

Um resultado grande, cujas linhas têm todas os mesmos campos, é devolvido orientado a colunas em vez de uma lista de objetos, de modo que os nomes dos campos são enviados uma só 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])). Os resultados pequenos, e qualquer resultado cujas linhas não partilhem um conjunto de campos idêntico, mantêm-se como listas normais de objetos — por isso surgem as duas formas, e o código que lê estas respostas diretamente deve tratar ambas. O envelope que as rodeia não muda e nenhum valor é convertido ou arredondado pelo caminho. Os agentes são informados desta forma quando se ligam e leem-na sem qualquer indicação da sua parte; a poupança ronda 30 % dos carateres e cerca de 15 % do orçamento de leitura de um agente em listagens típicas, o que deixa mais contexto livre para a sua pergunta propriamente dita. (Os dois valores diferem porque os nomes de campos repetidos são baratos de ler para um modelo — a poupança em carateres é sempre a maior das duas.)

Para o catálogo em tempo real, aponte o seu agente para o servidor e chame mcp_introspect (sem argumentos) — devolve o número atual de ferramentas, resumos por domínio e as assinaturas dos parâmetros. Utilize mcp_recipes para obter guias comuns com várias ferramentas (paginar listas grandes, instantâneo e depois modificação, reexecutar um passo que falhou, etc.).

Etiquetas e vistas

Todas as ferramentas upsert que definem etiquetas, para tabelas, fluxos de trabalho, passos, projetos, dimensões, vistas, editores, UDFs, ligações e armazéns, aceitam dois parâmetros: labels adiciona etiquetas e remove_labels remove-as. As restantes etiquetas do objeto mantêm-se. As remoções são aplicadas antes das adições, pelo que uma única chamada pode mudar o nome a uma etiqueta:

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

Remover uma etiqueta que o objeto não tem não faz nada.

As ferramentas de vistas trabalham com as vistas que vê no PlaidCloud:

• view_find lista vistas e view_describe devolve uma por ID ou nome.
• view_upsert cria uma vista ou atualiza uma existente no local. Uma atualização mantém o ID e as etiquetas da vista, e pode alterar apenas as etiquetas sem enviar novamente a consulta.
• view_organize elimina, muda o nome, duplica e move vistas.
• Escreva os parâmetros da consulta como marcadores %(name)s.

As vistas partilham a árvore de pastas das tabelas, pelo que deve utilizar table_organize para gerir as respetivas pastas.

Iniciadores de tarefas

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

Iniciador	O que lhe fornece
Importar um ficheiro CSV para uma tabela	O ficheiro e, opcionalmente, o projeto, a pasta que o contém e um nome para a nova tabela
Explicar uma variação de custos	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 de um projeto	O que procura e, opcionalmente, o projeto

Cada um é uma mensagem inicial, não um comando: o seu agente lê-a e depois conduz ele próprio as ferramentas, pelo que pode editá-la ou prosseguir a conversa a partir dela.

Importar um ficheiro sem conhecer o modelo de objetos

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

Lê texto delimitado — CSV, TSV e semelhantes. Um livro do Excel ou um ficheiro Parquet é rejeitado em vez de ser lido incorretamente; para os importar, utilize antes o passo de importação correspondente num fluxo de trabalho.

Em vez disso, o guia bulk_import_csv recebe a conta por nome e o ficheiro por nome ou caminho:

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

Resolve a conta no respetivo identificador, localiza o ficheiro, cria a tabela com as colunas e os tipos lidos do próprio ficheiro e carrega-a — pelo que não fornece nem um ID de conta nem uma especificação de colunas. table_name assume por predefinição o nome do ficheiro sem a extensão e table_path a raiz do projeto.

Indique a pasta quando a souber — 'document_path': 'raw/sales_2026.csv' — e a pesquisa fica confinada a ela. Um ficheiro indicado numa pasta só é encontrado nessa pasta: um ficheiro com o mesmo nome mais abaixo é oferecido como opção em vez de ser importado no seu lugar.

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 está a ajudar e, depois, chame novamente o guia com a resposta dela, devolvendo o candidato exatamente como foi fornecido. Quando o ficheiro não é encontrado, a resposta lista antes os nomes mais próximos e indica quantos ficheiros pesquisou, para que “não está lá” se distinga de “não está onde procurei”.

Nota

Um nome de ficheiro simples é pesquisado em todos os tipos de conta e, sem uma pasta para restringir, a pesquisa abrange a conta inteira. Numa conta de armazenamento de objetos (S3, Wasabi, GCS) isso custa uma listagem; no OneDrive, SFTP e Azure Blob, onde a primeira listagem abrange apenas um nível de diretório, a pesquisa faz uma segunda passagem, mais profunda. Indique a pasta, ou o caminho completo, sempre que o tiver — numa conta com muitos milhares de ficheiros, um nome simples é visivelmente mais lento.

Autenticação

O servidor MCP do PlaidCloud aceita dois métodos de autenticação:

1. OAuth 2.1 + PKCE através de Dynamic Client Registration (DCR). É o que a interface de conectores personalizados do Claude.ai utiliza e é também o método predefinido da ponte MCP do Claude Code. O cliente regista-se e redireciona-o para o início de sessão Keycloak do PlaidCloud. Depois de iniciar sessão, o PlaidCloud mostra uma página Application Access Request que indica a aplicação e o URI de redirecionamento para onde enviará as credenciais — aprove-a uma vez por autorização para obter o seu token. Trata-se de um controlo de segurança, não de uma formalidade: verifique se o nome da aplicação e o URI de redirecionamento correspondem ao cliente que está realmente a ligar e não aprove um pedido que não iniciou.
2. Token de portador estático num cabeçalho Authorization. Para ambientes de execução de agentes que não dispõem de um redirecionamento de navegador utilizável ou que pretendem um token de longa duração num ficheiro de configuração. O PlaidCloud disponibiliza uma página auxiliar para gerar um por si (veja abaixo).

Obter um token de portador estático

Abra este URL num separador do navegador em que já tenha sessão iniciada no PlaidCloud:

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

A página devolve um excerto JSON pronto a colar na configuração MCP do seu agente. Cada área de trabalho tem o seu próprio excerto.

O tempo de vida do token é determinado pela política de tempo de vida dos tokens de acesso do realm Keycloak (normalmente entre algumas horas e um dia). Para o renovar, recarregue o mesmo URL — a sessão do seu navegador gera novamente o token automaticamente.

Nota

Este método destina-se à fase inicial e a clientes que não conseguem concluir um redirecionamento OAuth. Para acesso de longa duração de agentes em produção — contas de serviço, executores de CI, tarefas agendadas — utilize OAuth sempre que o cliente o suporte. Os tokens de acesso pessoal estão previstos, mas ainda não se encontram geralmente disponíveis.

Escolher um cliente

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

• Claude Code — o agente de programação da Anthropic (CLI, extensão do VSCode, plug-in do JetBrains).
• Claude Desktop e Claude.ai — a aplicação Claude para consumidores (ambiente de trabalho) e a web (claude.ai) com “Custom Connectors”.
• Cursor — o editor de código nativo de IA.
• GitHub Copilot — o modo de agente do Copilot no VSCode.
• Google Gemini CLI — gemini-cli e Gemini Code Assist.
• ChatGPT — estado atual do suporte e solução alternativa recomendada.
• Grok — ligação dos conectores personalizados do Grok.
• Resolução de problemas — erros comuns e como os corrigir.