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 }

Atenção

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

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.

Template comentado

{
  "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:

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

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:

{
  "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[]

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

Atenção

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.

Exemplo — transport openapi

{
  "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 para o restante dos campos e endpoints envolvidos.

Próximos passos

• Empacotar um .adapp — como gerar o manifest e o checksum automaticamente.
• Importar um .adapp — como o manifest é validado no import.
• Templates e exemplos — manifests prontos para copiar.