---
title: Manifesto (manifest.json)
---

# Manifesto (manifest.json)

O `manifest.json` é o arquivo obrigatório na raiz de todo `.adapp`. Ele descreve identidade, transporte, endpoint e (para `http`/`sse`) as tools do provider MCP empacotado.

## Campos

| Campo | Tipo | Obrigatório | Regra/valores |
|-------|------|-------------|----------------|
| `format` | string | sim | deve ser exatamente `adapp/v1` |
| `checksum` | string | sim | formato `sha256:<64 hex>` (regex `^sha256:[a-f0-9]{64}$`) |
| `name` | string | sim | slug: `^[a-z0-9_-]{1,100}$`, max 100 |
| `label` | string | sim | max 120 |
| `description` | string\|null | não | max 500 |
| `category` | string\|null | não | max 60 |
| `icon` | string\|null | não | nome do arquivo do ícone dentro do ZIP (ex.: `icon.png`), max 500. `null` se sem ícone |
| `transport` | string | sim | um de: `http`, `sse`, `openapi` |
| `endpoint` | string (URL) | sim | URL HTTPS do servidor MCP |
| `tools` | array\|null | não | só em `http`/`sse`. Cada item: `{ "name": string (req), "inputSchema": object (req) }` |
| `required_secrets` | array\|null | não | cada item: `{ "key": string, "label": string, "required": bool }` |

<Cuidado>

`transport: stdio_curated` **não** é suportado no formato `adapp/v1` — o schema só aceita `http`, `sse` ou `openapi`. Esse transport é exclusivo de entradas do catálogo oficial gerenciadas internamente pela plataforma (ver [Referência MCP](../referencia)).

</Cuidado>

<Dica>

O campo `checksum` é **sempre** gerado pelo empacotador (`mcp:pack-app`) — você nunca escreve esse valor manualmente. Ele é calculado por último, depois que todo o resto do manifest e dos arquivos do pacote está definido.

</Dica>

## Template comentado

```json
{
  "format": "adapp/v1",
  "checksum": "sha256:<64 hex — gerado pelo empacotador>",
  "name": "test-app",
  "label": "Test App",
  "description": "App de teste",
  "category": "test",
  "icon": null,
  "transport": "http",
  "endpoint": "https://mcp.exemplo.com/v1",
  "required_secrets": null,
  "tools": [
    { "name": "test_tool", "inputSchema": { "type": "object", "properties": {} } }
  ]
}
```

## Subestrutura de `tools[]`

No modo `http`/`sse`, cada entrada de `tools[]` no manifest só precisa de `name` e `inputSchema`. A descrição completa da tool (com `description` e `required_secrets` próprios) fica no arquivo correspondente em `tools/<name>.json`:

```json
{
  "name": "test_tool",
  "description": "Test tool",
  "inputSchema": { "type": "object", "properties": {} },
  "required_secrets": null
}
```

No modo `openapi`, o campo `tools` do manifest fica ausente/`null` — as tools são derivadas do `openapi.json` no momento do import (ver [Empacotar um .adapp](./empacotar#openapi-tools)).

## http_binding (v1)

Cada arquivo `tools/<name>.json` pode carregar um bloco `http_binding` que descreve como a tool mapeia para uma chamada HTTP concreta — método, path, parâmetros e autenticação:

```json
{
  "version": "v1",
  "method": "POST",
  "path": "/v1/crawl",
  "server": "https://api.exemplo.com",
  "params": { "start_url": "body", "limit": "query", "X-Trace": "header", "id": "path" },
  "auth": { "type": "apiKey", "in": "header", "name": "X-API-Key", "credential_ref": "required_secrets[0].key" }
}
```

| Campo | Descrição |
|-------|-----------|
| `params` | mapa `argName → location`, onde `location` ∈ `body`, `query`, `header`, `path` |
| `auth` | omitido quando a tool não exige autenticação; tipos suportados: `apiKey` (com `in` + `name`), `bearer`, `basic` — todos carregam `credential_ref` |

`credential_ref` sempre aponta para uma entrada de `required_secrets` (ex.: `"required_secrets[0].key"`) — **o segredo em si nunca é embarcado no pacote**, só a referência à chave.

No modo `openapi`, o `http_binding` de cada tool é **gerado automaticamente** pelo converter a partir do spec — você não precisa escrevê-lo manualmente.

## Subestrutura de `required_secrets[]`

```json
{ "key": "ASAAS_API_KEY", "label": "Chave de API do Asaas", "required": true }
```

<Cuidado>

O shape de cada item de `required_secrets` é **estrito**: só `key`, `label` e `required`. Se um item trouxer a chave `value` (ou qualquer chave extra), o import é **rejeitado com 422** — segredos nunca viajam dentro do pacote, só as chaves e labels. Os valores reais são preenchidos depois, por um admin, no workspace que vai usar o servidor.

</Cuidado>

## Exemplo — transport `openapi`

```json
{
  "format": "adapp/v1",
  "checksum": "sha256:<64 hex>",
  "name": "openapi-app",
  "label": "OpenAPI App",
  "description": "App OpenAPI de teste",
  "category": "test",
  "icon": null,
  "transport": "openapi",
  "endpoint": "https://api.exemplo.com",
  "required_secrets": null
}
```

## Mapeamento manifest → mcp_catalog

No import, o manifest é convertido numa entrada `McpCatalog`:

| Campo do manifest | Destino |
|--------------------|---------|
| `icon` | coluna `image` do `mcp_catalog` |
| `name`, `label`, `category`, `description`, `transport` | colunas homônimas do `mcp_catalog` |
| `required_secrets` | coluna `required_secrets` do `mcp_catalog` |
| `endpoint` | **não** vai para o `mcp_catalog` — é gravado em `McpServer.config` |
| `tools` (http/sse) ou derivadas do `openapi.json` | persistidas como tools do servidor gerado |

Consulte também a [Referência MCP](../referencia) para o restante dos campos e endpoints envolvidos.

## Próximos passos

- [Empacotar um .adapp](./empacotar) — como gerar o manifest e o checksum automaticamente.
- [Importar um .adapp](./importar) — como o manifest é validado no import.
- [Templates e exemplos](./exemplos) — manifests prontos para copiar.