Integração MCP (acesso para ferramentas de IA)

O Canopy inclui um servidor MCP (Model Context Protocol) integrado que permite que ferramentas de IA — como Claude Desktop, GitHub Copilot, Cursor e VS Code — consultem e atualizem seus dados de EA diretamente. As ferramentas de IA também podem carregar artefatos (planilhas, diagramas BPMN, diagramas DrawIO, documentos livres) e transformá-los em cards, relações e diagramas que se ajustam ao metamodelo existente. Os usuários se autenticam através do provedor SSO existente, e cada ação respeita suas permissões individuais.

Este recurso é opcional e não inicia automaticamente. Requer que o SSO esteja configurado e que um administrador o ative na interface de configurações.

---

Como funciona

Ferramenta de IA (Claude, Copilot, etc.)
    │
    │  Protocolo MCP (HTTP + SSE)
    ▼
Servidor MCP do Canopy (:8001, interno)
    │
    │  OAuth 2.1 com PKCE
    │  delega ao provedor SSO
    ▼
Backend do Canopy (:8000)
    │
    │  RBAC por usuário
    ▼
PostgreSQL

1. Um usuário adiciona a URL do servidor MCP à sua ferramenta de IA.
2. Na primeira conexão, a ferramenta de IA abre uma janela do navegador para autenticação SSO.
3. Após o login, o servidor MCP emite seu próprio token de acesso (respaldado pelo JWT do Canopy do usuário). O token é renovado proativamente cerca de uma hora antes de expirar.
4. A ferramenta de IA usa este token para todas as solicitações subsequentes.
5. Cada consulta passa pelo sistema de permissões normal do Canopy — os usuários só veem os dados aos quais têm acesso.

---

Pré-requisitos

Antes de habilitar o MCP, você deve ter:

• SSO configurado e funcionando — O MCP delega a autenticação ao seu provedor SSO (Microsoft Entra ID, Google Workspace, Okta ou OIDC genérico). Consulte o guia de Autenticação e SSO.
• HTTPS com um domínio público — O fluxo OAuth requer uma URI de redirecionamento estável. Implante atrás de um proxy reverso com terminação TLS (Caddy, Traefik, Cloudflare Tunnel, etc.).

---

Configuração

Passo 1: Adicionar a URI de redirecionamento OAuth ao seu aplicativo SSO

No registro de aplicativo do seu provedor SSO (o mesmo que você configurou para o login do Canopy), adicione esta URI de redirecionamento:

https://seu-dominio.exemplo.com/mcp/oauth/callback

Isso é necessário para o fluxo OAuth que autentica os usuários quando se conectam a partir da ferramenta de IA.

Passo 2: Habilitar MCP nas configurações de administração

1. Vá para Configurações na área de administração e selecione a aba AI.
2. Role até a seção Integração MCP (acesso para ferramentas de IA).
3. Ative o interruptor para habilitar o MCP.
4. A interface mostrará a URL do servidor MCP e instruções de configuração para compartilhar com sua equipe.

aviso

O interruptor fica desabilitado se o SSO não estiver configurado. Configure o SSO primeiro.

---

Conectar ferramentas de IA

Uma vez habilitado o MCP, compartilhe a URL do servidor MCP com sua equipe. Cada usuário a adiciona à sua ferramenta de IA:

Claude Desktop

1. Abra Configurações > Conectores > Adicionar conector personalizado.
2. Insira a URL do servidor MCP: https://seu-dominio.exemplo.com/mcp
3. Clique em Conectar — uma janela do navegador abre para o login SSO.
4. Após a autenticação, o Claude pode consultar e atualizar seus dados de EA.

VS Code (GitHub Copilot / Cursor)

Adicione ao .vscode/mcp.json do seu workspace:

{
  "servers": {
    "canopy": {
      "type": "http",
      "url": "https://seu-dominio.exemplo.com/mcp/mcp"
    }
  }
}

O duplo /mcp/mcp é intencional — o primeiro /mcp/ é o caminho do proxy Nginx, o segundo é o endpoint do protocolo MCP.

---

Capacidades disponíveis

O servidor MCP expõe 47 ferramentas: 30 ferramentas de leitura distribuídas em nove clusters, e 17 ferramentas de escrita (13 aditivas, 4 destrutivas). Cada ferramenta carrega ToolAnnotations (readOnlyHint / destructiveHint / idempotentHint), de modo que conectores como o Claude Desktop possam exibir o grau de destrutividade em sua interface antes de o usuário aprovar uma chamada.

Segurança por execução simulada nas escritas

Toda ferramenta de escrita usa por padrão dry_run=true. Nesse modo, o backend executa todos os validadores e resolvedores, monta o plano completo e então reverte a transação, de modo que nada é persistido. A ferramenta de IA devolve a prévia ao usuário; somente após confirmação explícita ela deve chamar a ferramenta novamente com dry_run=false para confirmar. Isso impede que um agente entusiasmado introduza silenciosamente centenas de cards a partir de uma planilha interpretada incorretamente.

Para confirmações maiores, há uma segunda barreira: toda confirmação acima de MCP_BATCH_CONFIRMATION_THRESHOLD (padrão de 20 linhas) deve devolver um confirm_token de uso único, emitido pela execução simulada anterior. O token tem um TTL de 15 minutos. Isso é aplicado duas vezes — uma vez pelo wrapper MCP antes mesmo de chamar o backend, e novamente pelo próprio backend no endpoint de confirmação — de modo que um cliente que pule a etapa de execução simulada não consiga passar um lote grande e não revisado.

Lotes de mutação (trilha de auditoria)

Toda chamada de escrita — execução simulada ou não — abre uma linha em mutation_batches antes de tocar em qualquer dado, e cada evento que ela emite (card criado, relação inserida/atualizada, comentário publicado, …) é marcado com o id desse lote, além do nome da ferramenta chamadora e do usuário autenticado. A ferramenta get_change_history reconstrói o diff completo, evento a evento, de um lote a partir do seu id, e rollback_batch pode reverter as escritas de um lote (veja abaixo). Isso significa que qualquer alteração feita via MCP pode ser rastreada exatamente até quem executou qual ferramenta e quando — distinguindo-se da mesma ação realizada através da interface web.

Ferramentas de leitura

O servidor expõe 30 ferramentas de leitura distribuídas em nove clusters.

Cards & metamodelo

Ferramenta	Descrição
search_cards	Pesquisar e filtrar cards por tipo, status ou texto livre
get_card	Obter detalhes completos de um card por UUID
get_card_relations	Obter todas as relações conectadas a um card
get_card_hierarchy	Obter ancestrais e filhos de um card
list_card_types	Listar todos os tipos de card no metamodelo, com campos e configuração
get_relation_types	Listar tipos de relação, opcionalmente filtrados por tipo de card
resolve_card_refs	Pré-validar referências de cards baseadas em nome (ex.: "Vendas / Gestão de Clientes / CRM") antes de uma importação em massa — identifica correspondências resolvidas, ambíguas ou ausentes
analyze_impact	Análise de impacto em múltiplos saltos — percorre o grafo de relações a partir de um card até 3 saltos de profundidade, agrupado por profundidade, com filtros opcionais de tipo de relação e tipo de card

Painéis

Ferramenta	Descrição
get_dashboard	Painel de KPIs (contagens, qualidade de dados, aprovações, atividade)
get_landscape	Cards de um tipo agrupados por um tipo relacionado

GRC — Registro de riscos

Ferramenta	Descrição
list_risks	Lista paginada e filtrável de riscos EA (TOGAF Fase G)
get_risk	Detalhe de um risco com cards vinculados e trilha de auditoria
get_risk_metrics	KPIs + matrizes 4×4 de probabilidade × impacto inicial e residual
get_card_risks	Todos os riscos atualmente vinculados a um card específico

GRC — Conformidade

Ferramenta	Descrição
list_compliance_findings	Achados de conformidade agrupados por regulação (EU AI Act, GDPR, NIS2, DORA, SOC 2, ISO 27001)
get_compliance_overview	Pontuações de conformidade + matriz de status por regulação + metadados da última varredura

Governança & Entrega

Ferramenta	Descrição
list_principles	Princípios EA publicados (declaração, justificativa, implicações)
list_adrs	Architecture Decision Records, filtráveis por iniciativa / card / status / pesquisa
get_adr	ADR único com seções, cards vinculados, ADRs relacionados e trilha de assinaturas
list_soaws	Statements of Architecture Work de uma iniciativa

Relatórios

Ferramenta	Descrição
get_portfolio_report	Dados de gráfico de bolhas para um tipo de card (padrão: ajuste funcional × técnico)
get_cost_treemap	Treemap de custos de card, opcionalmente agrupado por um tipo relacionado
get_capability_heatmap	Mapa de calor hierárquico das capacidades de negócio
get_data_quality_report	Distribuição de completude por tipo de card

Contexto do card

Ferramenta	Descrição
get_card_stakeholders	Usuários + papéis atribuídos a um card
get_card_comments	Fio de comentários de um card
get_card_documents	Links de documentos anexados a um card

Diagramas

Ferramenta	Descrição
list_diagrams	Listar diagramas de desenho livre, opcionalmente filtrados por um card
get_diagram	Buscar um único diagrama por id, incluindo seu XML do DrawIO

Auditoria e histórico de alterações

Ferramenta	Descrição
get_change_history	Buscar um lote de mutação por id (retorna o lote e cada evento emitido nele, em ordem), ou navegar por lotes recentes filtrando por ator, nome da ferramenta ou origem (mcp / web / api)

Todas as ferramentas de leitura são regidas pelo RBAC do usuário autenticado — um visualizador simplesmente recebe uma lista vazia (ou um 403) para áreas que não pode ver; nada na camada MCP precisa ser configurado por ferramenta.

Ferramentas de escrita

O servidor expõe 17 ferramentas de escrita: 13 aditivas (ações de criação/atualização que não destroem dados) e 4 destrutivas (podem sobrescrever ou remover dados, embora várias delas sejam, em si, recuperáveis — veja as notas abaixo).

Cards & ciclo de vida

Ferramenta	Anotação	Descrição
create_cards_bulk	Aditiva	Criar vários cards em uma única chamada a partir de linhas extraídas de um artefato (por exemplo, linhas de planilha). Suporta referências ao pai por nome dentro do mesmo lote, com ordenação topológica no servidor.
update_cards_bulk	Aditiva	Atualizar vários cards em uma única chamada — patches em nível de campo com um diff antes/depois por linha na execução simulada. attributes é uma substituição completa por linha; strict_attributes=true rejeita chaves de campo desconhecidas com uma dica de recuperação.
transition_card_lifecycle	Aditiva	Mover um card através de ações de aprovação (approve / reject / reset), fases do ciclo de vida (phaseIn / active / phaseOut / endOfLife) ou valores de status (ACTIVE / PHASING_IN / PHASING_OUT / END_OF_LIFE / ARCHIVED). Retorna uma resposta pending com um link direto para a interface se o chamador não tiver a permissão, em vez de falhar diretamente.
archive_cards	Destrutiva	Excluir de forma reversível (arquivar) um ou mais cards, com uma prévia de cascata na execução simulada (filhos, relações órfãs). Cards arquivados são recuperáveis por 30 dias antes da exclusão automática definitiva. A exclusão definitiva/permanente é intencionalmente não exposta via MCP.

Relações & diagramas

Ferramenta	Anotação	Descrição
upsert_relations_bulk	Destrutiva	Criar ou excluir relações entre cards. action: "delete" é recusada por padrão (veja as salvaguardas abaixo) — é isso que torna esta ferramenta anotada como destrutiva, mesmo que as criações sejam o caso comum.
create_diagram	Aditiva	Criar um diagrama DrawIO livre, opcionalmente vinculado a cards existentes por UUID.
update_diagram	Destrutiva	Atualizar o XML, nome, descrição ou cards vinculados de um diagrama existente — drawio_xml substitui o canvas literalmente.
import_bpmn	Aditiva	Salvar um diagrama BPMN 2.0 em um card de Processo de Negócio existente, percorrendo o fluxo de rascunho → envio → aprovação. Se nenhum card correspondente existir, retorna um erro card_not_found apontando para create_cards_bulk, em vez de criar silenciosamente um card incompleto.

GRC — Registro de riscos

Ferramenta	Anotação	Descrição
create_risks	Aditiva	Criar um ou mais riscos, vinculando opcionalmente cards afetados na mesma chamada.
update_risks	Aditiva	Corrigir riscos existentes por id; linked_card_ids substitui o conjunto de vínculos de cards afetados quando fornecido.

Governança & entrega

Ferramenta	Anotação	Descrição
create_soaw	Aditiva	Criar um Statement of Architecture Work para uma iniciativa.
create_adr	Aditiva	Criar um Architecture Decision Record (criado como draft por padrão).
update_adr	Aditiva	Atualizar o título, as seções, o status ou os cards vinculados de um ADR existente.
sign_adr	Aditiva	Assinar um ADR. Retorna uma resposta pending com um link direto se o chamador não tiver adr.sign.

Colaboração

Ferramenta	Anotação	Descrição
add_card_comment	Aditiva	Publicar um comentário (opcionalmente em thread) em um card.
assign_stakeholders	Aditiva	Atribuir ou remover papéis de stakeholder em cards. O backend não possui um endpoint em massa para isso, portanto a ferramenta distribui cada operação individualmente dentro de um único lote de mutação.

Auditoria

Ferramenta	Anotação	Descrição
rollback_batch	Destrutiva	Reverter as escritas realizadas em um lote de mutação, percorrendo seus eventos em ordem reversa e aplicando o inverso de cada um. Cobre card.created / card.updated / card.archived / card.restored / relation.created / relation.upserted; outros tipos de evento aparecem como unsupported_events no plano da execução simulada. A própria reversão é registrada como um novo lote, de modo que o histórico nunca é apagado. Recusa a operação se um lote posterior tiver tocado nas mesmas entidades, a menos que force=true, o que exige admin.events.

O conteúdo armazenado por essas ferramentas (corpo de comentários, texto de seções de ADR/SoAW) é tratado como dado não confiável em leituras posteriores — o servidor nunca o interpreta como instruções, apenas o exibe.

Fluxo típico de importação de artefatos

Quando um usuário compartilha uma planilha com o agente de IA:

1. O agente chama list_card_types e get_relation_types para entender o metamodelo.
2. O agente faz o parse da planilha (no seu próprio contexto, não no MCP) e monta dicionários de linha.
3. Opcionalmente, o agente chama resolve_card_refs para verificar se alguma referência baseada em nome (pai/relação) se resolve sem ambiguidade.
4. O agente chama create_cards_bulk(cards=…, dry_run=True) e mostra a prévia ao usuário.
5. O usuário confirma; o agente chama novamente com dry_run=False (repetindo o confirm_token, se o lote estiver acima do limite de confirmação) para efetivar a operação.
6. Se houver colunas de relação, o agente então chama upsert_relations_bulk com o mesmo ciclo de execução simulada / confirmação.

O próprio servidor MCP nunca faz o parsing de arquivos enviados — a ferramenta de IA chamadora lê o artefato de origem (planilha, BPMN XML, DrawIO XML, PDF, imagem) no seu próprio contexto e envia linhas já estruturadas.

Salvaguardas das ferramentas de escrita

Defesa em profundidade além da execução simulada, para que um descuido do LLM não possa causar danos em massa:

• Limites de tamanho por chamada. As ferramentas de escrita MCP aplicam um limite bem menor que os endpoints subjacentes do importador Excel: 200 cards para create_cards_bulk / update_cards_bulk / archive_cards, 500 operações para upsert_relations_bulk. Grande o suficiente para qualquer upload realista de um único artefato, pequeno o suficiente para que uma prévia de execução simulada permaneça revisável. Os próprios endpoints do backend aceitam até 2000/5000 para o importador Excel legítimo da interface web.
• Token de confirmação acima do limite. Confirmações que envolvem mais de MCP_BATCH_CONFIRMATION_THRESHOLD linhas (padrão 20) devem devolver o confirm_token emitido pela execução simulada anterior. Aplicado tanto pelo wrapper MCP quanto pelo backend.
• Sem exclusão de relações por padrão. upsert_relations_bulk recusa operações action: "delete" — para remover relações, use a interface web, onde a ação é registrada sob a identidade do usuário com uma trilha de auditoria explícita. Entre em contato com o suporte para habilitar a exclusão de relações via MCP para sua instância.
• Sem exclusão definitiva. O conjunto de ferramentas omite deliberadamente a exclusão permanente de cards. archive_cards (exclusão reversível, com janela de restauração de 30 dias) e rollback_batch são as únicas formas de remover dados via MCP, e ambas são controladas por execução simulada e anotadas como destrutivas. Qualquer ferramenta futura que realize uma mutação irreversível precisa passar antes por uma discussão de RFC.
• Interruptor de desligamento. MCP_WRITES_ENABLED=false desativa as 17 ferramentas de escrita sem necessidade de reimplantar código. As 30 ferramentas de leitura continuam funcionando.
• Marcador de origem para auditoria. Cada requisição ao backend originada do servidor MCP carrega um cabeçalho X-Canopy-Origin: mcp (com lista de permissão no lado do servidor limitada a {mcp, web, api} — qualquer outro valor é descartado). Eventos emitidos a partir dessas requisições são marcados com origin: "mcp" no payload de auditoria, de modo que administradores possam filtrar as escritas originadas do MCP na linha do tempo. O cabeçalho X-Canopy-Batch propaga o id do lote de mutação atual em todas as chamadas de uma única invocação de ferramenta.

Essas salvaguardas são configuradas por instância; entre em contato com o suporte para solicitar uma alteração em qualquer um dos padrões abaixo:

Variável	Padrão	Efeito
MCP_WRITES_ENABLED	true	Interruptor principal das ferramentas de escrita. false → MCP somente leitura.
MCP_MAX_CARDS_PER_CALL	200	Limite rígido de linhas por chamada para create_cards_bulk, update_cards_bulk, archive_cards.
MCP_MAX_RELATIONS_PER_CALL	500	Limite rígido de operações upsert_relations_bulk por requisição.
MCP_ALLOW_RELATION_DELETE	false	Quando true, upsert_relations_bulk aceita operações action: "delete".
MCP_BATCH_CONFIRMATION_THRESHOLD	20	Número de linhas acima do qual uma confirmação deve devolver um confirm_token de uma execução simulada anterior.
MCP_REQUIRE_DRYRUN_FIRST	true	Quando true, uma confirmação acima do limite sem uma execução simulada anterior correspondente na mesma sessão é rejeitada. Entre em contato com o suporte para desativar isso em pipelines de automação confiáveis.

Recursos

URI	Descrição
turbo-ea://types	Todos os tipos de card no metamodelo
turbo-ea://relation-types	Todos os tipos de relação
turbo-ea://dashboard	KPIs do painel e estatísticas resumidas

Prompts guiados

Prompt	Descrição
analyze_landscape	Análise em várias etapas: visão geral do painel, tipos, relações
find_card	Pesquisar um card por nome, obter detalhes e relações
explore_dependencies	Mapear o que um card depende e o que depende dele

---

Permissões

Papel	Acesso
Administrador	Configurar as definições de MCP (permissão admin.mcp). Acesso completo de leitura e escrita através do MCP.
Todos os usuários autenticados	Acesso de leitura regido pelo RBAC existente. As ferramentas de escrita exigem a permissão de backend correspondente à ação que realizam.

O acesso a dados através do MCP — leitura ou escrita — segue o mesmo modelo RBAC da interface web. Se um usuário não pode criar cards na interface do inventário, também não pode criá-los via MCP; não há permissões de dados específicas do MCP. Permissões selecionadas por ferramenta:

Permissão	Controla
inventory.create	create_cards_bulk
inventory.edit	update_cards_bulk, transições de ciclo de vida/status via transition_card_lifecycle
inventory.approval_status	Transições de aprovação (approve / reject / reset) via transition_card_lifecycle
inventory.archive	archive_cards
relations.manage	upsert_relations_bulk
diagrams.manage	create_diagram, update_diagram
bpm.edit	import_bpmn (rascunho); a publicação exige adicionalmente card.approval_status no processo, detida pelo papel de stakeholder process_owner, admin ou bpm_admin
risks.manage	create_risks, update_risks
comments.create	add_card_comment
stakeholders.manage	assign_stakeholders
soaw.create	create_soaw
adr.create	create_adr, update_adr
adr.sign	sign_adr
admin.events	rollback_batch(force=True) — para sobrepor um conflito de reversão com um lote posterior

A permissão admin.mcp controla quem pode gerenciar as configurações de MCP. Está disponível apenas para o papel de Administrador por padrão. Papéis personalizados podem receber esta permissão através da página de administração de Papéis.

Várias ferramentas de escrita degradam graciosamente em vez de falhar de forma abrupta quando o chamador não tem uma permissão: transition_card_lifecycle e sign_adr retornam uma resposta pending com um link direto para a interface web, para que uma pessoa com a permissão correta possa concluir a ação por lá.

---

Segurança

• Autenticação delegada por SSO: Os usuários se autenticam através do provedor SSO corporativo. O servidor MCP nunca vê ou armazena senhas (no modo HTTP).
• OAuth 2.1 com PKCE: O fluxo de autenticação utiliza Proof Key for Code Exchange (S256) para prevenir a interceptação de códigos de autorização.
• RBAC por usuário: Cada consulta MCP — leitura ou escrita — é executada com as permissões do usuário autenticado. Sem contas de serviço compartilhadas.
• Execução simulada por padrão nas escritas: As ferramentas de escrita usam por padrão uma prévia de validar-e-reverter. A ferramenta de IA deve chamar explicitamente de novo com dry_run=false antes que algo seja persistido, e cada alteração é auditada sob a identidade do usuário como parte de um lote de mutação.
• Barreira de token de confirmação em confirmações grandes: Confirmações acima do limite configurável de linhas exigem um token emitido por uma execução simulada anterior, verificado de forma independente tanto pelo wrapper MCP quanto pelo backend.
• Trilha de auditoria completa com reversão: get_change_history reconstrói o diff de qualquer lote a partir do seu id; rollback_batch pode reverter os tipos de evento suportados de um lote, sendo essa própria reversão registrada como um novo lote auditável.
• Sem parsing de arquivos no MCP: O próprio servidor MCP não aceita PDFs, arquivos Excel, imagens ou outros artefatos binários. A ferramenta de IA chamadora os processa no seu próprio contexto e envia linhas estruturadas. Isso mantém a superfície de ataque reduzida e evita expor o servidor a entradas binárias malformadas.
• Sem exclusão definitiva via MCP: A exclusão permanente de cards não é exposta como ferramenta. Os únicos caminhos de remoção são archive_cards (exclusão reversível, com recuperação de 30 dias) e rollback_batch.
• Rotação de tokens: Tokens de acesso expiram após 1 hora e são renovados proativamente. Tokens de renovação duram 30 dias. Códigos de autorização são de uso único e expiram após 10 minutos.
• Porta apenas interna: O container MCP expõe a porta 8001 apenas na rede Docker interna. Todo acesso externo passa pelo proxy reverso Nginx.
• Armazenamento de tokens em instância única: Os tokens OAuth são mantidos em memória no container MCP. Se você executar várias réplicas atrás de um load balancer, fixe as sessões em uma única instância ou espere que os usuários precisem se reautenticar após um failover — os tokens não são compartilhados entre réplicas.

---

Solução de problemas

Problema	Solução
O interruptor MCP está desabilitado nas configurações	O SSO deve ser configurado primeiro. Vá para Configurações > aba Autenticação e configure um provedor SSO.
«host not found» nos logs do Nginx	Isso indica que o serviço MCP não está acessível na sua instância — entre em contato com o suporte.
O callback OAuth falha	Verifique se você adicionou https://seu-dominio.exemplo.com/mcp/oauth/callback como URI de redirecionamento no registro do aplicativo SSO.
A ferramenta de IA não consegue se conectar	Verifique se a URL do servidor MCP mostrada em Configurações corresponde à usada pela sua ferramenta de IA, e se é acessível a partir da máquina do usuário.
O usuário obtém resultados vazios	O MCP respeita as permissões RBAC. Se um usuário tem acesso restrito, verá apenas os cards que seu papel permite.
A ferramenta de escrita retorna writes_disabled	As escritas estão atualmente desativadas nesta instância. As ferramentas de leitura continuam funcionando; entre em contato com o suporte para reativar as escritas, se necessário.
Confirmação recusada com confirm_token_required	O lote está acima de MCP_BATCH_CONFIRMATION_THRESHOLD linhas. Execute novamente com dry_run=true primeiro e depois repasse o confirm_token retornado na chamada de confirmação.
A conexão cai após 1 hora	A ferramenta de IA deveria lidar com a renovação de tokens automaticamente. Caso contrário, reconecte.