Como Usar um Servidor MCP para Documentação de Arquitetura

Assistentes de codificação com IA se tornaram indispensáveis. O Claude Code ajuda a refatorar sistemas complexos. O Cursor acelera o desenvolvimento de features. O GitHub Copilot sugere implementações. Mas todas essas ferramentas compartilham um ponto cego comum: elas não conhecem sua arquitetura.

Quando você pede a um assistente de IA para "adicionar um novo endpoint ao User Service", ele não sabe que seu User Service se comunica com um Auth Service via gRPC, armazena dados em PostgreSQL, publica eventos para o Kafka e tem um conjunto especifico de requisitos de segurança documentados nos seus ADRs. A IA adivinha, você corrige, e metade do ganho de produtividade evapora.

Servidores MCP resolvem isso. Eles dão aos assistentes de IA acesso estruturado a sua documentação de arquitetura, transformando seu design de sistema em uma fonte de dados consultável e acionável. Este guia cobre tudo que você precisa saber sobre usar um servidor MCP para documentação de arquitetura -- o que e MCP, por que importa e como configurar com o Archyl.

O Que e MCP (Model Context Protocol)?

MCP -- o Model Context Protocol -- é um padrão aberto criado pela Anthropic para conectar assistentes de IA a ferramentas e fontes de dados externas. Ele define uma forma estruturada para modelos de IA descobrirem, invocarem e receberem resultados de capacidades externas.

Pense no MCP como um adaptador universal. Antes do MCP, cada assistente de IA tinha sua própria forma proprietária de integrar com ferramentas externas. O MCP padroniza isso, criando um único protocolo que funciona em diferentes assistentes de IA.

Um servidor MCP é um serviço que expõe um conjunto de ferramentas através do protocolo MCP. Cada ferramenta tem um nome, uma descrição, parâmetros de entrada e formato de saída. Quando um assistente de IA se conecta a um servidor MCP, ele descobre as ferramentas disponíveis e pode invoca-las conforme necessário durante uma conversa.

Para documentação de arquitetura, isso significa que seu modelo de arquitetura se torna um conjunto de ferramentas consultáveis e modificáveis que qualquer assistente de IA compatível com MCP pode usar. A IA não precisa parsear arquivos ou adivinhar sobre a estrutura do seu sistema -- ela pode consultar diretamente a fonte autoritativa de verdade.

Por Que a Arquitetura Precisa de MCP

A documentação de arquitetura está na intersecção de varias necessidades que o MCP atende perfeitamente.

Contexto e Tudo para Desenvolvimento Assistido por IA

A qualidade do código gerado por IA é diretamente proporcional a qualidade do contexto que a IA possui. Quando um assistente de IA entende sua arquitetura -- quais serviços existem, como se comunicam, quais tecnologias usam, quais restrições se aplicam -- ele gera código que se encaixa naturalmente no seu sistema.

Sem contexto arquitetural, assistentes de IA fazem suposições. Eles podem sugerir uma REST API quando seu serviço usa gRPC. Podem criar uma conexão direta com o banco de dados quando sua arquitetura exige passar por uma camada de serviço. Podem propor uma chamada síncrona quando seu sistema usa comunicação event-driven.

MCP da aos assistentes de IA acesso a arquitetura real, eliminando esses desencontros.

Documentação de Arquitetura é Dado Estruturado

Diferente de documentação em formato livre (wikis, paginas do Confluence, arquivos README), documentação de arquitetura modelada no framework C4 é inerentemente estruturada. Systems contem containers. Containers contem components. Elementos têm technologies, descrições e relationships. ADRs têm statuses e elementos afetados.

Essa estrutura se mapeia naturalmente para ferramentas MCP. Cada tipo de elemento arquitetural se torna uma entidade consultável. Cada operação (list, get, create, update) se torna uma ferramenta. O assistente de IA pode navegar pelo modelo de arquitetura da mesma forma que um desenvolvedor navega por um sistema de arquivos.

Documentação Deve Ser Bidirecional

A maioria das ferramentas de documentação são somente leitura do ponto de vista da API. Você pode visualizar documentos, mas modifica-los requer abrir uma aplicação especifica. MCP habilita interação bidirecional: o assistente de IA pode tanto ler quanto escrever no modelo de arquitetura.

Isso significa que um assistente de IA pode não apenas consultar sua arquitetura mas também propor modificações -- adicionar um novo componente, criar um relationship, redigir um ADR. O desenvolvedor revisa e aprova essas mudanças, mas a IA faz o trabalho mecânico de atualizar a documentação.

Documentação que ninguém abre continua sendo lida

A documentação de arquitetura sempre teve um problema de descoberta. Você a escreve, ela fica em um wiki ou em uma ferramenta de diagramas, e os engenheiros fazem a pergunta no Slack em vez de abri-la.

O MCP muda o lugar onde a documentação é lida. Você não vai procurá-la; seu assistente vai, toda vez que você pergunta "como funciona o processamento de pagamentos?". A resposta vem da sua arquitetura documentada e não dos dados de treinamento do modelo, e um engenheiro novo a recebe no primeiro dia sem saber onde a documentação fica.

Há um efeito colateral que vale a pena ter. Documentação consultada o dia todo é corrigida quando está errada, porque alguém percebe a resposta errada. Documentação que ninguém lê apodrece em silêncio.

Servidor MCP do Archyl: 56 Ferramentas para Arquitetura

O Archyl fornece uma das implementações de servidor MCP mais abrangentes para documentação de arquitetura. Com 181 ferramentas organizadas em todo o escopo de modelagem de arquitetura, ele cobre tudo, desde consultar o modelo C4 ate gerenciar releases e rastrear drift.

Aqui está uma visão geral das categorias de ferramentas.

Consultando o Modelo C4

As ferramentas principais de consulta permitem que o assistente de IA explore sua arquitetura em cada nível:

  • list_systems / get_project_c4_model -- Descobrir todos os software systems em um projeto
  • list_containers / list_components -- Navegar pela hierarquia C4
  • list_relationships -- Entender como elementos se conectam
  • get_element_technologies -- Ver a stack tecnológica de qualquer elemento
  • get_element_owners -- Saber quem e dono do que

Essas ferramentas habilitam consultas em linguagem natural sobre sua arquitetura. Quando você pergunta "De quais bancos de dados o Order Service depende?", a IA pode listar os relationships do Order Service, filtrar por containers de banco de dados e retornar uma resposta precisa.

Gerenciando Elementos de Arquitetura

Ferramentas de escrita permitem que o assistente de IA modifique o modelo de arquitetura:

  • create_system / update_system / delete_system -- Gerenciar software systems
  • create_container / update_container / delete_container -- Gerenciar containers
  • create_component / update_component / delete_component -- Gerenciar components
  • create_relationship / update_relationship / delete_relationship -- Gerenciar conexões

Essas ferramentas são particularmente poderosas para manter a documentação atualizada durante o desenvolvimento. Quando você adiciona um novo serviço ao seu codebase, pode pedir ao assistente de IA para adicionar o container correspondente ao modelo de arquitetura, definir suas technologies e criar os relationships apropriados -- tudo sem sair da sua IDE.

Architecture Decision Records

Ferramentas de ADR trazem documentação de decisões para o workflow de IA:

  • list_adrs / get_adr -- Consultar decisões existentes
  • create_adr / update_adr -- Criar novos ADRs ou atualizar existentes
  • link_adr_to_element -- Conectar decisões a elementos afetados

Quando você está discutindo uma escolha tecnológica com seu assistente de IA, ele pode verificar ADRs existentes para decisões relacionadas, redigir um novo ADR para a decisão atual e vincula-lo aos elementos arquiteturais relevantes.

Contratos de API e Event Channels

Ferramentas de documentação de integração cobrem limites de serviço:

  • list_api_contracts / create_api_contract -- Gerenciar especificações de API
  • list_event_channels / create_event_channel -- Modelar comunicação async
  • link_api_contract / link_event_channel -- Conectar specs a elementos

Essas ferramentas ajudam a manter a conexão entre arquitetura e implementação. Quando você cria um novo endpoint de API, a IA pode verificar se existe um contrato de API para aquele serviço e sugerir atualiza-lo. Funciona no sentido contrário também: se os seus serviços expõem servidores MCP, o Archyl documenta as ferramentas deles como contratos de API, e o playground MCP permite chamá-las ao vivo.

Documentação e Colaboração

Ferramentas mais amplas de documentação suportam workflows de equipe:

  • create_documentation / update_documentation -- Gerenciar docs do projeto
  • create_comment / list_comments -- Anotar elementos de arquitetura
  • list_flows / create_flow -- Documentar fluxos de usuário e sistema
  • get_drift_score / compute_drift_score -- Verificar precisão da documentação

Releases e Métricas

Ferramentas operacionais conectam arquitetura a entrega:

  • create_release / list_releases -- Rastrear deployments
  • get_dora_metrics / get_dora_trend -- Medir performance de engenharia
  • list_environments -- Entender alvos de deploy

Exemplos Reais: MCP em Ação

Aqui estão exemplos concretos de como desenvolvedores usam o servidor MCP do Archyl em seu workflow diário.

Exemplo 1: Consultando Systems no Claude Code

Você está trabalhando no Claude Code e precisa entender a arquitetura antes de fazer mudanças:

Voce: Quais systems e containers nosso projeto tem?

Claude: Deixe-me verificar sua arquitetura.
[Chama list_systems, depois list_containers para cada system]

Seu projeto "E-Commerce Platform" tem 3 systems:
1. E-Commerce Platform (software_system)
   - API Gateway (Go, Kong)
   - User Service (Go, PostgreSQL)
   - Order Service (Java, PostgreSQL)
   - Product Service (Node.js, MongoDB)
   - Notification Service (Python, Redis)
   - Event Bus (Kafka)

2. Stripe (external_system)
   - Gateway de processamento de pagamentos

3. SendGrid (external_system)
   - Servico de email transacional

A IA retorna dados reais da sua arquitetura documentada, não uma alucinação.

Exemplo 2: Criando Components no Cursor

Você está adicionando um novo modulo a um serviço e quer documenta-lo:

Voce: Acabei de adicionar um componente RateLimiter ao API Gateway.
     Ele usa Redis e a biblioteca golang.org/x/time/rate.
     Pode adicionar a nossa arquitetura?

Cursor: Vou adicionar ao seu modelo C4.
[Chama create_component com name="RateLimiter",
 container="API Gateway", technologies=["Redis", "Go"]]
[Chama create_relationship do RateLimiter
 para o container Redis]

Pronto. Adicionei o componente RateLimiter ao API Gateway
e criei um relationship com seu container Redis.

A documentação é atualizada em segundos, sem sair da IDE.

Exemplo 3: Verificando Drift Antes de uma Refatoração

Antes de um grande esforço de refatoração, você quer saber quão precisa é a documentação:

Voce: Qual e nosso drift score atual? Ha servicos
     nao documentados?

Claude: Deixe-me verificar.
[Chama get_drift_score]
[Chama get_drift_details]

Seu drift score e 78/100 (Bom).

Problemas detectados:
- O Search Service esta rodando em producao mas nao
  documentado no seu modelo C4
- O Analytics Service tem 2 relationships nao documentados
  com o Data Warehouse
- A lista de technologies do API Gateway esta faltando "Redis"
  (adicionado recentemente para rate limiting)

Gostaria que eu corrigisse esses problemas?

A IA identifica exatamente o que está desatualizado e pode corrigir automaticamente.

Exemplo 4: Redigindo um ADR

Durante uma discussão de design sobre mudar de REST para gRPC na comunicação interna entre serviços:

Voce: Estamos considerando mudar a comunicacao interna entre
     servicos de REST para gRPC. Pode redigir um ADR e verificar
     se temos decisoes existentes sobre isso?

Claude: Deixe-me verificar ADRs existentes primeiro.
[Chama list_adrs]

Encontrei um ADR relacionado:
- ADR-007: "Usar REST para todas as APIs internas" (Status: Accepted)
  Isso foi decidido ha 18 meses.

Vou redigir um novo ADR para substitui-lo.
[Chama create_adr com title="Migrar Comunicacao Interna
 de REST para gRPC"]

Criado ADR-015 com:
- Contexto: A comunicacao atual baseada em REST adiciona
  overhead de serializacao...
- Decisao: Adotar gRPC com Protocol Buffers para toda
  nova comunicacao interna entre servicos...
- Status: Proposed
- Substitui: ADR-007

Gostaria que eu vinculasse aos servicos afetados?

A IA verifica decisões relacionadas, redige um novo ADR e oferece vincula-lo aos elementos arquiteturais relevantes.

Exemplo 5: Entendendo Impacto Antes de Mudanças

Antes de modificar um serviço, você quer entender o raio de impacto:

Voce: Preciso mudar o schema do banco de dados do Order Service.
     O que mais depende do Order Service?

Claude: Deixe-me rastrear as dependencias.
[Chama list_relationships filtrado por Order Service]
[Chama get_element_owners para elementos dependentes]

O Order Service tem estes dependentes:
- API Gateway -> Order Service (REST, gerenciamento de pedidos)
- Order Service -> Payment Service (gRPC, processamento de pagamentos)
- Order Service -> Event Bus (publica OrderCreated,
  OrderUpdated, OrderCancelled events)
- Notification Service consome Order events do Event Bus
- Analytics Service consome Order events do Event Bus

Proprietarios:
- Order Service: Platform Team
- Payment Service: Payments Team
- Notification Service: Platform Team
- Analytics Service: Data Team

Mudancas de schema podem afetar o Payment Service (dependencia
direta) e qualquer consumidor de Order events. Recomendo
coordenar com as equipes de Payments e Data.

Configurando o Servidor MCP do Archyl

Começar com o servidor MCP do Archyl leva apenas alguns minutos. Veja como configura-lo para os assistentes de IA mais comuns. O servidor é stateless desde a revisão 2026-07-28 do protocolo.

Configuração para Claude Code

Adicione o servidor MCP do Archyl a sua configuração do Claude Code:

{
  "mcpServers": {
    "archyl": {
      "url": "https://api.archyl.com/mcp",
      "headers": {
        "X-API-Key": "YOUR_ARCHYL_API_KEY"
      }
    }
  }
}

Uma vez configurado, o Claude Code descobre automaticamente todas as 181 ferramentas e pode usa-las em qualquer conversa.

Configuração para Cursor

O Cursor suporta servidores MCP através de suas configurações. Adicione o Archyl na seção MCP:

{
  "mcpServers": {
    "archyl": {
      "url": "https://api.archyl.com/mcp",
      "headers": {
        "X-API-Key": "YOUR_ARCHYL_API_KEY"
      }
    }
  }
}

Apos adicionar a configuração, reinicie o Cursor. As ferramentas do Archyl aparecem na lista de ferramentas MCP, e o Cursor pode usa-las durante geração de código e refatoração.

Configuração para Outras Ferramentas Compatíveis com MCP

Qualquer ferramenta que suporte o protocolo MCP pode se conectar ao servidor MCP do Archyl. O servidor expõe um endpoint MCP padrão com descoberta de ferramentas, então clientes compatíveis detectam e listam automaticamente as ferramentas disponíveis.

Geração de API Key

Gere sua API key MCP a partir do dashboard do Archyl:

  1. Navegue ate as configurações da sua organização
  2. Vá para a seção de API
  3. Crie uma nova API key com as permissões apropriadas
  4. Copie a key para sua configuração de servidor MCP

Recomendamos criar API keys separadas para diferentes casos de uso (ex.: uma para Claude Code, uma para CI/CD) para que você possa rota-las independentemente.

Melhores Praticas para Documentação de Arquitetura com MCP

Comece com Somente Leitura

Quando você configura o servidor MCP pela primeira vez, comece com consultas somente leitura. Fique confortável com a capacidade do assistente de IA de explorar sua arquitetura antes de habilitar operações de escrita. Isso constrói confiança na precisão e confiabilidade da ferramenta.

Revise Mudanças Geradas por IA

Quando o assistente de IA cria ou modifica elementos de arquitetura, revise as mudanças antes de considera-las finais. Os recursos de histórico e versão do Archyl permitem ver o que mudou e reverter se necessário. A IA é um assistente poderoso, mas decisões arquiteturais devem sempre ter supervisão humana.

Combine MCP com Architecture as Code

MCP e architecture as code são complementares. Use MCP para consultas interativas e atualizações rápidas durante o desenvolvimento. Use architecture as code (o arquivo archyl.yaml) para definições autoritativas e versionadas que passam por code review. As duas abordagens se reforçam mutuamente.

Use MCP em Code Reviews

Durante code reviews, peca ao assistente de IA para verificar se as mudanças de código se alinham com a arquitetura documentada. "Este novo endpoint de API corresponde ao contrato de API documentado para este serviço?" ou "Estas queries de banco de dados estão passando pela camada de serviço conforme documentado?" A IA pode validar código contra o modelo de arquitetura em tempo real.

Ensine Sua Equipe as Ferramentas Disponíveis

A maior barreira para adoção de MCP é a consciência. A maioria dos desenvolvedores não percebe quais perguntas a IA pode responder sobre sua arquitetura. Compartilhe exemplos, crie um guia rápido de consultas uteis e demonstre workflows MCP em reuniões de equipe.

O Futuro da Documentação de Arquitetura com IA

Servidores MCP representam uma mudança fundamental em como equipes interagem com documentação de arquitetura. Em vez de documentação ser um artefato passivo que desenvolvedores leem (ou mais frequentemente, não leem), ela se torna uma participante ativa no workflow de desenvolvimento.

Quando seu assistente de IA pode consultar a arquitetura antes de gerar código, verificar conformidade apos mudanças e atualizar documentação conforme o sistema evolui, a barreira entre "trabalhar no sistema" e "documentar o sistema" desaparece.

Documentação de arquitetura deixa de ser algo que você mantém separadamente e se torna algo entrelaçado em cada interação de desenvolvimento. Cada pergunta que você faz a IA, cada mudança de código que faz, cada discussão de design que tem -- todas podem ser informadas por e refletidas no modelo de arquitetura.

Este é o futuro que o Archyl está construindo. O servidor MCP é a ponte entre desenvolvimento com IA e documentação de arquitetura estruturada. E com 181 ferramentas cobrindo todo o escopo de modelagem de arquitetura, e abrangente o suficiente para suportar qualquer workflow que sua equipe precise.

Comece com o servidor MCP do Archyl e de ao seu assistente de IA o contexto arquitetural que ele estava faltando.