Servidor MCP - Archyl Docs

Conecte assistentes de IA como Claude, Cursor e VS Code à sua documentação de arquitetura

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:

  • Listar e navegar pelos seus projetos
  • Criar e modificar elementos de arquitetura
  • Gerar documentação
  • Responder perguntas sobre sua arquitetura

Ferramentas 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

O servidor MCP requer uma chave de API para autenticação. 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.

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"
      }
    }
  }
}
  1. 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"
    }
  }
}
  1. 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"
    }
  }
}
  1. 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.

Ferramentas Disponíveis

Uma vez conectado, seu assistente de IA pode usar estas ferramentas:

Gerenciamento de Projetos

Ferramenta Descrição
list_projects Listar todos os seus projetos
get_project Obter detalhes do projeto
create_project Criar um novo projeto

Elementos de Arquitetura

Ferramenta Descrição
list_systems Listar sistemas em um projeto
create_system Criar um novo sistema
list_containers Listar containers em um sistema
create_container Criar um novo container
list_components Listar componentes em um container
create_component Criar um novo componente

Relacionamentos

Ferramenta Descrição
list_relationships Listar relacionamentos
create_relationship Criar um relacionamento

Documentação

Ferramenta Descrição
list_adrs Listar Registros de Decisão de Arquitetura
create_adr Criar um novo ADR
list_docs Listar documentação
create_doc Criar documentação

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..."

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 ?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
  • Verifique se sua chave de API tem as permissões necessárias

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