Uso por assistentes de IA

Escolha de design Aedifica: assistentes consultam dados e trabalham em rascunhos com uma chave própria, limitada à organização. A documentação abaixo descreve o código atual; a disponibilidade remota depende de deploy e IAM, sem publicação ou ligação externa confirmada neste lote.

Escolher o contrato

• MCP remoto: consultar Servidor MCP para o catálogo de ferramentas, schemas, transporte Streamable HTTP, configuração Codex e limitações de autenticação no ChatGPT. O servidor usa os serviços internos da API; inclui um entrypoint stdio local e OAuth remoto na Etapa 1, sem pacote publicado nem geração automática de ferramentas OpenAPI.
• HTTP REST: consultar a especificação OpenAPI local, autenticação e convenções. Usar apenas as operações descritas nesse contrato. Os schemas MCP podem expor operações adicionais; não inferir um endpoint REST a partir do nome de uma ferramenta.

Não há garantia de compatibilidade por nome de cliente. O cliente MCP tem de suportar o transporte e a autenticação documentados. Em particular, o ChatGPT não apresenta chaves API personalizadas neste fluxo; o fluxo OAuth está implementado na Etapa 1; configuração pública e registo/teste do conector pelo Walter continuam pendentes, como explicado na página MCP.

Chaves e permissões

Um proprietário ou administrador cria a chave em Definições → API e webhooks (/app/:ws/settings/api). A predefinição é read; ativar write apenas quando necessário. Os únicos âmbitos atuais são read e write, independentes entre si. Não existe expiração configurável na UI nem âmbitos granulares por recurso.

Guardar o segredo no ambiente do processo cliente como AEDIFICA_API_KEY, sem o colocar no prompt, configuração versionada ou URL. A chave só é mostrada na criação/rotação. Revogar ou rodar a chave pela app quando necessário. O servidor revalida a chave e o papel do criador a cada pedido.

Exemplo MCP com dados fictícios

O fluxo seguinte usa nomes do registo atual; o cliente envia cada objeto por tools/call. As referências têm de existir na organização da chave.

{"name":"list_projects","arguments":{"limit":25}}

Após identificar o projeto pretendido, criar apenas o cabeçalho de um orçamento em rascunho:

{"name":"create_quote_draft","arguments":{"data":{"folderId":"projeto_exemplo","name":"Remodelação WC","date":"2026-11-04"},"idempotencyKey":"orcamento-wc-exemplo-001"}}

Reutilizar a mesma chave de idempotência ao repetir esta criação. As linhas são alteradas separadamente com update_draft_positions, usando {id,version,patch:{editor:…}} e o schema completo do editor publicado pela ferramenta; não enviar blocos arbitrários na criação. Uma alteração com versão desatualizada gera conflito: voltar a ler e rever o estado antes de nova alteração.

Exemplo de consulta ao catálogo:

{"name":"search_catalog","arguments":{"query":"argamassa","type":"materials","limit":25}}

Seguir nextCursor enquanto existir, mesmo com páginas filtradas vazias. As listas são limitadas a 1–100 registos por pedido; não assumir que uma página representa o catálogo completo.

Ações que exigem uma pessoa

request_finalize_document, request_send_document e request_approve_time criam pedidos pendentes com ligação para revisão na app. Não finalizam, numeram, enviam ou aprovam automaticamente. Uma pessoa autorizada regista a decisão na app e prossegue pelo fluxo existente. A confirmação escrita no chat não substitui essa decisão; mesmo uma decisão registada como confirmada não executa a ação.

Não existe ferramenta MCP para gerir chaves. As anotações das ferramentas são informação para o cliente, não autorização. Os limites de 60 pedidos/minuto/chave e corpo de 1 MB são partilhados com a integração REST. O PDF gera um artefacto e uma ligação privada temporária: exige leitura, mas não é marcado como idempotente.