Tools MCP como API Contracts: documente o que seus agentes podem fazer
Há alguns meses lançamos os API Contracts: especificações OpenAPI, gRPC, GraphQL e AsyncAPI, ligadas diretamente aos elementos C4 que as implementam e consomem. A ideia era simples — a descrição precisa e legível por máquina de uma interface pertence dentro da sua arquitetura, não em uma página do Notion que ninguém atualiza.
Restava uma interface que não havíamos coberto. A mais nova. Aquela que seus serviços expõem cada vez mais, não para outros serviços, mas para os agentes de IA: MCP.
Um servidor MCP publica um conjunto de tools — cada um com um nome, uma descrição e um JSON Schema para suas entradas. Isso é um contrato. É o contrato que decide o que um agente tem permissão para fazer no seu sistema. E até hoje, ele era completamente invisível na sua documentação de arquitetura.
Agora não mais. MCP agora é um tipo de API Contract de primeira classe no Archyl — o quinto, ao lado de HTTP, gRPC, GraphQL e AsyncAPI.
A parte difícil: os tools MCP não vivem em um arquivo
Os outros quatro tipos de contrato compartilham uma suposição — existe um arquivo de spec em um repositório. openapi.yaml. schema.graphql. Você aponta o Archyl para ele e nós o renderizamos.
O MCP quebra isso. Os tools de um servidor MCP são definidos no código, e a lista completa e autoritativa só existe em tempo de execução, quando um cliente chama tools/list e recebe o schema de cada tool. Não há um mcp.yaml universal para apontar.
Então construímos duas entradas.
Duas formas de adicionar um contrato MCP
Cole-o. Se você já tem a saída do seu tools/list, cole-a. O Archyl a valida e renderiza cada tool — sua descrição e seus parâmetros de entrada em uma tabela legível.
Ou simplesmente nos dê a URL. Diga ao Archyl onde fica seu servidor MCP, adicione opcionalmente um token de acesso (como header ou como parâmetro de URL), e clique em Descobrir tools. O Archyl se conecta, executa o handshake e traz automaticamente cada tool e parâmetro. Sem copiar e colar, sem um arquivo mantido à mão.
Como funciona a descoberta ao vivo — e por que é segura
A descoberta acontece no seu navegador, não nos nossos servidores. Quando você clica em Descobrir tools, seu navegador fala diretamente com seu servidor MCP.
Essa escolha importa:
- Seu token nunca sai do seu navegador. O Archyl armazena os tools descobertos e os detalhes de conexão — a URL, o transporte, onde o token vai — mas nunca o token em si.
- Nenhum acesso do lado do servidor à sua rede. Como a chamada se origina na sua máquina, não há como apontá-la para os serviços internos de outra pessoa. Toda a categoria de riscos do tipo SSRF simplesmente não existe aqui.
- Ela alcança localhost e servidores privados. Está testando um servidor rodando no seu laptop ou dentro da sua rede? Funciona, porque é o seu navegador que o enxerga.
A única contrapartida é o CORS: um servidor de terceiros precisa permitir a origem do Archyl para que seu navegador possa ler a resposta. Para servidores que você controla, é uma linha de configuração; para o restante, a opção de colar está sempre disponível.
Ligado à sua arquitetura, como qualquer outro contrato
Uma vez dentro, um contrato MCP se comporta como qualquer outro. Ligue-o ao container ou componente que hospeda o servidor. Navegue por cada tool e seu schema de entrada. Redescubra-o quando o servidor mudar. Ele aparece ao lado dos seus contratos REST e GraphQL, porque para os agentes que o chamam, é uma API igualmente real.
Isso transforma seu contrato MCP em algo genuinamente novo: um mapa do que seus agentes de IA têm permissão para fazer em uma determinada parte do seu sistema — documentado, ligado e revisável.
Nós usamos em nós mesmos
O Archyl é, ele próprio, um servidor MCP — 178 tools que permitem conduzir sua arquitetura a partir do Claude Code, Cursor ou qualquer cliente MCP. O primeiro contrato MCP que criamos foi o nosso: apontar o Archyl para o seu próprio endpoint, descobrir todos os 178 tools, ligá-lo à plataforma. Nossa superfície de agente agora se documenta sozinha.
Experimente
Abra um projeto, vá em API Contracts, crie um novo e escolha MCP. Cole seu tools/list, ou insira uma URL e clique em Descobrir tools.
Seus serviços já conversam com agentes. Agora sua arquitetura sabe o que eles estão dizendo.