Importar um .adapp

Endpoint

POST /api/mcp/apps/import

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

O workspace do importador é identificado pelo token (JWT); não é enviado no corpo da requisição.

Exemplo

curl -X POST https://SEU_HOST/api/mcp/apps/import \
  -H "Authorization: Bearer $TOKEN" \
  -F "[email protected]"

Resposta

201 Created com a entrada de catálogo criada (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 itens:

• Entrada global no catálogo: marcada como customizada, com registro de qual workspace importou. O schema de configuração expõe o campo url, com o endpoint do pacote como valor padrão.
• Servidor MCP isolado no seu workspace: configurado com a url do endpoint, com 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:

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

Atenção

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.

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

Atenção

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

Proteções aplicadas na abertura do pacote

• Extensão, tipo e tamanho — validados antes de qualquer leitura do ZIP.
• Caminhos permitidos — só são aceitos entries dentro da lista permitida (manifest.json, ícone na raiz, tools/*.json, openapi.json); qualquer caminho fora dessa lista é rejeitado.
• Zip-bomb — cap de 50 entries, cap de 50 MB descomprimidos, razão de compressão máxima de 100:1 por entry.
• Checksum — recomputado a partir do conteúdo do pacote e comparado com o checksum do manifest; qualquer divergência rejeita o import.
• Schema do manifest — validado contra o schema adapp/v1 (ver 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.

Atenção

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.

Próximos passos

• Empacotar um .adapp — como gerar o pacote antes de importar.
• Templates e exemplos — checklist de validação antes de importar.