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, que o perfil MCP esteja ativado no Docker Compose 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

Um usuário adiciona a URL do servidor MCP à sua ferramenta de IA.
Na primeira conexão, a ferramenta de IA abre uma janela do navegador para autenticação SSO.
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.
A ferramenta de IA usa este token para todas as solicitações subsequentes.
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: Iniciar o serviço MCP

O servidor MCP é um perfil opcional do Docker Compose. Adicione --profile mcp ao seu comando de inicialização:

docker compose --profile mcp up -d

Isso inicia um container Python leve (porta 8001, apenas interno) junto ao backend e frontend. O Nginx redireciona automaticamente as solicitações /mcp/ para ele — se o container não estiver em execução, as solicitações recebem um 502 limpo em vez de derrubar o proxy de borda.

Passo 2: Configurar variáveis de ambiente

Adicione estas ao seu arquivo .env:

CANOPY_PUBLIC_URL=https://seu-dominio.exemplo.com
MCP_PUBLIC_URL=https://seu-dominio.exemplo.com/mcp

Variável	Padrão	Descrição
`CANOPY_URL`	`http://backend:8000`	URL interna do backend com a qual o container MCP se comunica (nome do serviço Docker — raramente precisa de alteração).
`CANOPY_PUBLIC_URL`	`http://localhost:8920`	A URL pública da sua instância Canopy.
`MCP_PUBLIC_URL`	`http://localhost:8920/mcp`	A URL pública do servidor MCP (usada nas URIs de redirecionamento OAuth e nos metadados).
`MCP_PORT`	`8001`	Porta interna do container MCP (raramente precisa de alteração).

Passo 3: 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 4: Habilitar MCP nas configurações de administração

Vá para Configurações na área de administração e selecione a aba AI.
Role até a seção Integração MCP (acesso para ferramentas de IA).
Ative o interruptor para habilitar o MCP.
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

Abra Configurações > Conectores > Adicionar conector personalizado.
Insira a URL do servidor MCP: https://seu-dominio.exemplo.com/mcp
Clique em Conectar — uma janela do navegador abre para o login SSO.
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.

Teste local (modo stdio)

Para desenvolvimento local ou testes sem SSO/HTTPS, você pode executar o servidor MCP em modo stdio — o Claude Desktop o inicia diretamente como um processo local.

1. Instalar o pacote do servidor MCP:

pip install ./mcp-server

2. Adicionar à configuração do Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "canopy": {
      "command": "python",
      "args": ["-m", "canopy_mcp", "--stdio"],
      "env": {
        "CANOPY_URL": "http://localhost:8000",
        "CANOPY_EMAIL": "[email protected]",
        "CANOPY_PASSWORD": "sua-senha"
      }
    }
  }
}

Neste modo, o servidor se autentica diretamente com email/senha (sem OAuth) e renova o JWT do Canopy automaticamente em segundo plano.

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:

O agente chama list_card_types e get_relation_types para entender o metamodelo.
O agente faz o parse da planilha (no seu próprio contexto, não no MCP) e monta dicionários de linha.
Opcionalmente, o agente chama resolve_card_refs para verificar se alguma referência baseada em nome (pai/relação) se resolve sem ambiguidade.
O agente chama create_cards_bulk(cards=…, dry_run=True) e mostra a prévia ao usuário.
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.
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. Operadores podem habilitar essa opção com MCP_ALLOW_RELATION_DELETE=true.
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.

As variáveis de ambiente de salvaguarda no container MCP:

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. Operadores podem desativar isso para 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	O serviço MCP não está em execução. Inicie-o com `docker compose --profile mcp up -d`. A configuração do Nginx lida com isso de forma elegante (resposta 502, sem queda).
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 `MCP_PUBLIC_URL` corresponde à URL acessível a partir da máquina do usuário. Certifique-se de que o HTTPS está funcionando.
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`	`MCP_WRITES_ENABLED=false` nesta implantação. As ferramentas de leitura continuam funcionando; peça a um operador 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.

Como funciona​

Pré-requisitos​

Configuração​

Passo 1: Iniciar o serviço MCP​

Passo 2: Configurar variáveis de ambiente​

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

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

Conectar ferramentas de IA​

Claude Desktop​

VS Code (GitHub Copilot / Cursor)​

Teste local (modo stdio)​

Capacidades disponíveis​

Segurança por execução simulada nas escritas​

Lotes de mutação (trilha de auditoria)​

Ferramentas de leitura​

Ferramentas de escrita​

Fluxo típico de importação de artefatos​

Salvaguardas das ferramentas de escrita​

Recursos​

Prompts guiados​

Permissões​

Segurança​

Solução de problemas​