Importar um .adapp

Endpoint

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

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

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:

{
  "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/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).
• 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.