---
title: Importar um .adapp
---

# Importar um .adapp

## Endpoint

```http
POST /api/mcp/apps/import
```

| Aspecto | Valor |
|---------|-------|
| Autenticação | JWT (`Authorization: Bearer <token>`) |
| Permissão | `agent mcp.connect` + Gate `admin-or-owner` |
| Throttle | 10 requisições por minuto |
| Corpo | `multipart/form-data`, campo `package` = arquivo `.adapp` |

O `workspace_id` do importador é registrado a partir do JWT (nunca do body — fail-secure: se o token não trouxer `workspace_id`, a requisição retorna `422`).

## Exemplo

```bash
curl -X POST https://SEU_HOST/api/mcp/apps/import \
  -H "Authorization: Bearer $TOKEN" \
  -F "package=@minha-api.adapp"
```

## Resposta

`201 Created` com o recurso `McpCatalog` criado (`data`) e a lista de `required_secrets` ainda pendentes de preenchimento por um admin.

## O que o import cria

O import é **idempotente por `name`** — importar o mesmo `.adapp` de novo atualiza a entrada existente em vez de duplicar. Ele cria (ou atualiza) dois registros:

- **`McpCatalog` global**: `is_custom = true`, com `imported_by_workspace_id` registrando quem importou. `config_schema` é gerado como `{ "type": "object", "properties": { "url": { "type": "string", "default": "<endpoint>" } } }`.
- **`McpServer` isolado por workspace**: `config = { "url": "<endpoint>" }`, status inicial `pending`.

Para `transport: http` ou `sse` cujas tools ainda estejam vazias, o import dispara **auto-discovery em background** (best-effort — falha na descoberta não derruba o import, o server fica `pending` até um `refresh-tools` manual).

Erros de validação ou de segurança retornam `422`:

```json
{
  "errors": {
    "package": ["mensagem de erro"]
  }
}
```

<Cuidado>

**A publicação é no catálogo GLOBAL**, não por workspace. Depois do import, a integração fica visível para **todos** os workspaces da plataforma — confirme que é essa a intenção antes de importar.

</Cuidado>

## Segurança e limites

Todo pacote passa por uma cadeia de proteções antes de ser aceito.

| Guard | Limite |
|-------|--------|
| Tamanho do upload (borda) | 10 MB |
| Tamanho do arquivo (arquivo aberto) | 20 MB |
| Máx. de entries no ZIP | 50 |
| Máx. total descomprimido | 50 MB |
| Máx. razão de compressão por entry (anti zip-bomb) | 100:1 |
| Tamanho máx. do ícone | 512 KB |
| MIME de ícone aceitos | `image/png`, `image/jpeg`, `image/webp` (verificado por magic bytes, não pela extensão) |
| Extensão do upload | deve ser `.adapp` |
| MIME do upload | `application/zip`, `application/octet-stream`, `application/x-zip-compressed` |

<Cuidado>

**SVG é explicitamente rejeitado como ícone** (`image/svg+xml`, `text/html` e XML em geral são bloqueados) — proteção contra XSS embutido em ícone. A validação verifica os magic bytes do arquivo, não confia na extensão declarada. Ícones aceitos são salvos no disco público do import em `mcp/icons/<uuid>.<ext>`.

</Cuidado>

### Proteções aplicadas na abertura do pacote

- **Extensão/MIME/tamanho** — validados na borda, no FormRequest, antes de qualquer leitura do ZIP.
- **Zip-slip** — só são aceitos entries dentro do allowlist (`manifest.json`, ícone na raiz, `tools/*.json`, `openapi.json`); qualquer path traversal é rejeitado.
- **Zip-bomb** — cap de 50 entries, cap de 50 MB descomprimidos, razão de compressão máxima de 100:1 por entry, extração feita em streaming.
- **Checksum** — recomputado a partir do conteúdo do pacote e comparado em tempo constante (`hash_equals`) com o `checksum` do manifest; qualquer divergência rejeita o import.
- **Schema do manifest** — validado contra o schema `adapp/v1` (ver [Manifesto](./manifesto)).
- **SSRF Guard** — o `endpoint` do manifest é resolvido e bloqueado se apontar para IP privado, loopback ou link-local (RFC 1918, `127.0.0.1`, `::1`, `169.254.0.0/16` etc.). Detalhes completos em [Referência MCP → SSRF Guard](../referencia#ssrf-guard).

<Cuidado>

Endpoints precisam ser **HTTPS públicos**. Pacotes apontando para endereços internos, VPN ou localhost são rejeitados pelo SSRF Guard — mesmo padrão aplicado ao cadastro de servidores MCP customizados.

</Cuidado>

## Próximos passos

- [Empacotar um .adapp](./empacotar) — como gerar o pacote antes de importar.
- [Templates e exemplos](./exemplos) — checklist de validação antes de importar.