Servidor MCP

O Archyl oferece um servidor Model Context Protocol (MCP) que permite que assistentes de IA interajam com sua documentação de arquitetura. Isso possibilita uma exploração e documentação de arquitetura poderosa e assistida por IA.

O que é MCP?

O Model Context Protocol (MCP) é um protocolo aberto que permite que assistentes de IA acessem ferramentas e fontes de dados externas de forma segura. Com o servidor MCP do Archyl, seu assistente de IA pode:

• Navegar e consultar seus projetos e todo o seu modelo C4
• Criar e modificar elementos de arquitetura, relacionamentos e diagramas
• Ler e escrever ADRs, documentação, contratos de API e canais de eventos
• Verificar regras de conformidade, pontuações de desvio, métricas DORA e responsabilidades antes de escrever código
• Acompanhar releases, solicitações de mudança, comentários e histórico

Clientes compatíveis

O servidor MCP do Archyl funciona com:

• Antigravity - IDE com IA do Google
• Claude Code - Ferramenta CLI da Anthropic
• Claude Desktop - Aplicativo desktop do Claude
• Cursor - Editor de código focado em IA
• OpenAI Codex - Assistente de codificação com IA da OpenAI
• VS Code - Com GitHub Copilot Chat
• Warp - Terminal moderno com integração de IA
• Windsurf - IDE com IA da Codeium

Autenticação

Chave de API (recomendado)

A maioria dos clientes se autentica com uma chave de API. Dependendo da ferramenta que você está usando:

• Ferramentas com suporte a headers (Claude Code, Cursor, Warp, Windsurf, Antigravity): Use o header X-API-Key
• Ferramentas sem suporte a headers (Claude Desktop, VS Code, OpenAI Codex): Use o parâmetro de query ?apiKey=SUA_CHAVE_DE_API na URL

Gere uma chave de API na página Perfil → Chaves de API.

Os escopos da chave determinam o que o assistente pode fazer: uma chave somente leitura pode chamar todas as ferramentas list_* e get_*, enquanto create_*, update_*, delete_* e import_dsl exigem uma chave com escopo de escrita. Entregar ao seu agente uma chave somente leitura é a maneira mais simples de deixá-lo explorar sua arquitetura sem poder alterá-la.

OAuth 2.1

O servidor também implementa OAuth 2.1 com registro dinâmico de clientes, para clientes que se conectam por meio de um login no navegador em vez de uma chave colada (os escopos mcp:read e mcp:write espelham os escopos da chave de API acima). Aponte esse tipo de cliente para o mesmo endpoint e ele descobrirá o fluxo automaticamente através de:

https://api.archyl.com/.well-known/oauth-authorization-server
https://api.archyl.com/.well-known/oauth-protected-resource

Configuração

Antigravity

1. Abra o Antigravity e clique no menu "..." no painel do Agent
2. Selecione "MCP Servers" > "Manage MCP Servers" > "View raw config"
3. Adicione em ~/.gemini/antigravity/mcp_config.json:

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

4. Reinicie o Antigravity para aplicar as alterações

Nota: O Antigravity usa serverUrl em vez de url para servidores MCP baseados em HTTP.

Claude Code

Crie um arquivo .mcp.json na raiz do seu projeto:

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

Execute o Claude Code — ele detectará automaticamente o servidor MCP.

Claude Desktop

1. Abra as configurações do Claude Desktop
2. Navegue até Developer → MCP Servers
3. Clique em "Add Server" e adicione:

{
  "mcpServers": {
    "archyl": {
      "url": "https://api.archyl.com/mcp?apiKey=SUA_CHAVE_DE_API"
    }
  }
}

4. Reinicie o Claude Desktop

Nota: Os conectores remotos do Claude Desktop não suportam headers personalizados, então a chave de API deve ser passada como parâmetro de query na URL.

Cursor

Crie um arquivo .cursor/mcp.json no seu projeto:

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

Reinicie o Cursor para carregar o servidor MCP.

OpenAI Codex

Abra ou crie ~/.codex/config.toml e adicione:

[mcp_servers.archyl]
url = "https://api.archyl.com/mcp?apiKey=SUA_CHAVE_DE_API"

Reinicie o Codex CLI ou IDE para aplicar as alterações.

VS Code

1. Abra as configurações do VS Code (Cmd/Ctrl + ,)
2. Pesquise "MCP" e clique em "Edit in settings.json"
3. Adicione:

{
  "mcp": {
    "servers": {
      "archyl": {
        "url": "https://api.archyl.com/mcp?apiKey=SUA_CHAVE_DE_API"
      }
    }
  }
}

Warp

1. Abra o Warp e vá para Settings > MCP Servers
2. Clique em "Add Server" e cole a configuração:

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

3. Reinicie o Warp para aplicar as alterações

Windsurf

Abra o arquivo de configuração MCP em ~/.codeium/windsurf/mcp_config.json:

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

Reinicie o Windsurf para aplicar as alterações.

Referência de ferramentas

O servidor expõe 189 ferramentas. Elas seguem um padrão de nomenclatura previsível, então um assistente geralmente consegue adivinhar a correta:

A maioria das ferramentas com escopo de projeto recebe um projectId; as ferramentas com escopo de elemento recebem um elementId mais um elementType (o nível C4: 1 = sistema, 2 = container, 3 = componente, 4 = código). Peça ao seu assistente para chamar list_projects primeiro — ele obterá dali os IDs de que precisa.

Seu cliente descobre essa lista automaticamente via tools/list, então ela está sempre em sincronia com o servidor. As tabelas abaixo são para humanos decidirem o que pedir.

Perfis de ferramentas

189 ferramentas é mais do que um agente de código precisa para uma tarefa delimitada — anunciar todas custa contexto. Adicione ?profile=coding à URL do MCP (ou envie o cabeçalho X-Archyl-Tool-Profile: coding) para reduzir a superfície a 16 ferramentas: contexto focado na tarefa, o ciclo de sessões de trabalho do harness e as verificações de conformidade/diff. Omita o parâmetro (ou use profile=full) para o catálogo completo.

Contexto do agente (4)

Comece por aqui: estas ferramentas dão ao assistente o panorama da arquitetura em uma única chamada, em vez de várias.

Sessões de trabalho do Harness (8)

O ciclo de trabalho governado para agentes de código: declare uma unidade de trabalho para obter contexto focado e bloqueios consultivos, envie heartbeats enquanto trabalha e finalize com um resultado que pode abrir uma solicitação de mudança de arquitetura. Além disso, memória de projeto: memorize fatos para os próximos trabalhadores e recupere o que as sessões anteriores aprenderam.

Projetos (7)

Organizações e times (5)

Elementos C4 (15)

Sistemas (nível 1), containers (nível 2), componentes (nível 3) e elementos de código (nível 4).

Relacionamentos (4)

Layout do diagrama e overlays (5)

Documentação (11)

Registros de Decisão de Arquitetura (6)

Contratos de API (8)

Contratos OpenAPI, gRPC, GraphQL, AsyncAPI e de ferramentas MCP.

Canais de eventos (8)

Fluxos e quadros brancos (8)

Comentários e discussões (11)

Responsabilidade (6)

Tecnologias e radar (10)

Releases e ambientes (10)

Solicitações de mudança de arquitetura (6)

Regras de conformidade (9)

Detecção de desvio (4)

Métricas DORA, ROI e previsões (4)

Histórico e viagem no tempo (5)

Insights (3)

Marketplace e widgets (15)

Webhooks (7)

Arquitetura de toda a organização (9)

Visões entre projetos e artefatos no nível da organização.

Arquitetura como código (1)

Exemplos de Conversas

Explorando a Arquitetura

Você: "Quais sistemas existem no meu projeto de e-commerce?"

IA: Usa a ferramenta list_systems "Seu projeto de e-commerce tem 4 sistemas: Web Store, Payment Service, Inventory System e Notification Service..."

Criando Elementos

Você: "Adicione um novo container chamado Redis Cache ao sistema Web Store para armazenamento de sessões"

IA: Usa a ferramenta create_container "Criei o container Redis Cache no sistema Web Store com a descrição 'Cache em memória para armazenamento de sessões'."

Documentação

Você: "Crie um ADR para nossa decisão de usar PostgreSQL em vez de MongoDB"

IA: Usa a ferramenta create_adr "Criei o ADR-001: Seleção de Tecnologia de Banco de Dados, documentando a decisão de usar PostgreSQL por sua conformidade ACID e flexibilidade de consultas..."

Antes de escrever código

Você: "Estou prestes a adicionar limitação de taxa ao fluxo de checkout. O que eu preciso saber?"

IA: Usa find_relevant_context e impact_of "O checkout toca o API Gateway e o serviço Orders. Alterar o gateway afeta 6 containers downstream. O ADR-014 já determina o uso do Redis para throttling, e uma regra de conformidade proíbe novas dependências do Session store legado..."

Verificação de governança

Você: "Estamos nos desviando da arquitetura documentada?"

IA: Usa get_drift_score e run_conformance_check "A pontuação de desvio é 82% (contra 91% no mês passado). Duas violações: o serviço Search chama o banco de dados de Orders diretamente, e Payments usa um cliente HTTP não aprovado..."

Endpoint

Streamable HTTP (MCP)

https://api.archyl.com/mcp

Use este endpoint para conectar seu assistente de IA à documentação de arquitetura do Archyl. Ele suporta o protocolo de transporte Streamable HTTP.

Resolução de Problemas

Falha na Conexão

• Verifique se sua chave de API é válida
• Certifique-se de que a URL do endpoint está correta
• Verifique sua conexão de rede

Falha na Autenticação

• Para ferramentas com suporte a headers: Verifique se o header X-API-Key está configurado corretamente
• Para ferramentas sem suporte a headers: Verifique se o parâmetro de query ?apiKey= está na URL
• Certifique-se de que sua chave de API não expirou

Ferramenta Não Encontrada

• Certifique-se de que está usando o nome correto da ferramenta — veja a referência de ferramentas, ou peça ao seu cliente para atualizar a lista de ferramentas
• Alguns clientes fazem cache de tools/list; reinicie o cliente após atualizar

Ferramentas de Escrita Rejeitadas

• create_*, update_*, delete_* e import_dsl precisam de uma chave de API com escopo de escrita — uma chave somente leitura só pode chamar list_* e get_*
• Verifique seu plano de assinatura: alguns recursos (webhooks, conexões com o marketplace, execuções de agentes gerenciados) dependem do plano

Problemas Específicos do Antigravity

• Certifique-se de usar serverUrl (não url) na configuração
• O local da configuração é ~/.gemini/antigravity/mcp_config.json

Problemas Específicos do OpenAI Codex

• Verifique se a sintaxe TOML está correta em ~/.codex/config.toml
• Use [mcp_servers.archyl] como nome da tabela

Problemas Específicos do Warp

• Navegue até Settings > MCP Servers para gerenciar configurações
• Reinicie o Warp após fazer alterações na configuração

Boas Práticas

Seja Específico

Ao pedir para sua IA modificar a arquitetura, seja específico:

• Inclua nomes de projetos
• Especifique tipos de elementos
• Forneça descrições

Revise as Alterações

Sempre revise os elementos criados pela IA:

• Verifique se nomes e descrições estão corretos
• Confirme se os relacionamentos estão corretos
• Atualize conforme necessário

Use para Exploração

O MCP é ótimo para:

• Explorar rapidamente arquiteturas grandes
• Gerar documentação inicial
• Responder perguntas sobre seus sistemas