---
title: O formato .adapp
---

# O formato .adapp

## A analogia do instalador

Um `.adapp` ("Atende Direito App") é um **instalador** de provider MCP. Em vez de cadastrar um servidor MCP na mão — endpoint, tools, secrets, ícone — você empacota tudo isso num único arquivo `.zip` com extensão `.adapp` e importa de uma vez no catálogo global da plataforma.

É o mecanismo de **portabilidade e distribuição** de integrações MCP curadas: quem empacota gera o pacote uma vez, quem importa publica a integração pronta para todos os workspaces usarem.

<Dica>

Se você só quer conectar um servidor MCP ao **seu** workspace, não precisa de `.adapp` — cadastre um servidor customizado direto (veja [Cadastrar MCP Server](../cadastrar-mcp-server)). O `.adapp` existe para quando você quer **publicar** uma integração no catálogo global.

</Dica>

## Formato atual

A versão vigente do formato é `adapp/v1`, declarada no campo `format` do `manifest.json`.

## Estrutura interna do ZIP

O layout dentro do `.adapp` muda conforme o `transport` declarado no manifest.

### Transport `http` ou `sse`

```text
pacote.adapp (ZIP)
├── manifest.json          (obrigatório)
├── icon.png               (opcional; png/jpg/jpeg/webp)
└── tools/
    ├── crawl.json          (uma tool por arquivo)
    ├── search.json
    └── ...
```

Cada arquivo em `tools/` descreve uma tool: `name`, `description`, `inputSchema`, `required_secrets` e, opcionalmente, um `http_binding` (ver [Manifesto → http_binding](./manifesto#http-binding-v1)).

### Transport `openapi`

```text
pacote.adapp (ZIP)
├── manifest.json          (obrigatório)
├── icon.png               (opcional)
└── openapi.json           (spec OpenAPI completo)
```

No modo `openapi` não existe pasta `tools/` — as tools são **derivadas do spec** no momento do import (cada combinação path + método vira uma tool).

## Ciclo de vida

```text
Empacotar (mcp:pack-app)  →  .adapp  →  Importar (POST /mcp/apps/import)  →  Catálogo global  →  Usar no fluxo
```

1. Um desenvolvedor empacota um provider MCP (existente no catálogo ou a partir de um spec OpenAPI) com `php artisan mcp:pack-app`.
2. O comando gera o arquivo `.adapp`.
3. Um admin importa o pacote via `POST /api/v1/mcp/apps/import`.
4. A integração passa a existir no catálogo MCP global, visível para todos os workspaces.
5. Qualquer workspace pode cadastrar um servidor a partir dessa entrada e usá-la no Flow Builder.

## Checksum: por que existe

Todo `manifest.json` carrega um campo `checksum` no formato `sha256:<64 hex>`. Ele é calculado a partir do conteúdo canônico do manifest, do hash de cada arquivo de tool (ou do `openapi.json`) e do hash do ícone. No import, esse checksum é **recalculado e comparado em tempo constante** — qualquer byte alterado no pacote invalida a verificação e o import é rejeitado.

Isso garante que o pacote que chega até o import é **exatamente** o que o empacotador gerou — sem adulteração no caminho.

<Cuidado>

Nunca edite um `.adapp` (ou o `manifest.json` dentro dele) na mão depois de gerado. Qualquer alteração muda o checksum e o pacote passa a ser rejeitado no import. Se precisar mudar algo, refaça o empacotamento com `mcp:pack-app`.

</Cuidado>

## Próximos passos

- [Manifesto (manifest.json)](./manifesto) — referência completa dos campos do manifest.
- [Empacotar um .adapp](./empacotar) — como gerar o pacote com `mcp:pack-app`.
- [Importar um .adapp](./importar) — como publicar o pacote no catálogo global.
- [Templates e exemplos](./exemplos) — pacotes prontos para copiar.