Servidor MCP

Conecte o seu agente de programação ao Bondry: o endereço, o token bkm_, os escopos, as ferramentas e a configuração do cliente.

Hospedamos um servidor MCP para quem escreve módulo e tema. O seu agente faz a ele as mesmas perguntas que esta documentação responde, roda as mesmas checagens que a revisão roda e publica pelas mesmas rotas que o seu pipeline chamaria.

Não é acesso ao Bondry instalado de ninguém. Operar um site é o conector de IA do produto, que é outro assunto e mora do lado do Bondry.

O endereço#

Código

https://mcp.bondry.org/v1/<hash>
Authorization: Bearer bkm_<12 hex>.<segredo>

O hash identifica; o token autentica. O identificador da URL é o mesmo que a sua conta já usa nos links de download, e é ele que diz de quem é a sessão. Ele não é senha, e não basta sozinho: um token só vale na URL do próprio dono, e qualquer outro endereço responde 404, sem nunca confirmar se aquele identificador é de alguém.

O token é emitido na sua conta, em Acesso MCP. Ele aparece uma vez, é revogável, tem escopos e registra o último uso. Guardamos apenas o hash dele, então não existe tela que o mostre de novo.

Os escopos#

Marcados na emissão, e nunca ampliados depois.

Escopo	Permite
`docs`	ler a documentação de desenvolvedor, o esquema do manifesto, os ganchos, as permissões, os tokens de design e os eventos
`validate`	rodar as checagens de pacote e de manifesto
`publish`	cadastrar artefato, anunciar versão e enviar pacote
`status`	ler o estado de revisão e o histórico de entregas

publish nasce desmarcado. Um token sem ele não publica, e uma chamada de ferramenta que precise dele é recusada pela própria ferramenta, com o motivo, enquanto a sessão continua. Precisa de um token mais largo? Emita outro e revogue o antigo.

As ferramentas#

Leitura (escopo docs)

Ferramenta	Devolve
`bondry_docs_search`	trechos desta documentação, com o caminho da página e o do arquivo
`bondry_manifest_schema`	o esquema de `module.json` ou `theme.json`, campo a campo, com o que é obrigatório
`bondry_hooks`	os slots de interface e como um módulo preenche um deles
`bondry_permissions`	o modelo de permissões e as regras de independência por trás dele
`bondry_design_tokens`	os controles do customizer e as variáveis CSS a que eles se ligam
`bondry_events`	o modelo de eventos e os métodos de ciclo de vida que o kernel chama

Verificação (escopo validate)

Ferramenta	Faz
`bondry_validate_manifest`	valida um `module.json` ou `theme.json` colado, campo a campo
`bondry_validate_package`	roda a revisão automática num zip enviado na própria chamada: caminho para fora, symlink, bomba, tamanho, manifesto, slug, versão, a tradução em inglês obrigatória e a varredura estática
`bondry_review_preflight`	as duas acima, mais cada bandeira com o arquivo e a linha

Publicação (escopo publish, e status nas duas leituras)

Ferramenta	Faz
`bondry_register_artifact`	cadastra um artefato e reserva o slug, ou atualiza os metadados de um que você já publica
`bondry_announce_release`	anuncia uma versão, sem enviar um byte
`bondry_upload_package`	envia o zip de uma versão anunciada
`bondry_artifact_status`	estado da revisão, versão publicada, pendências e último anúncio
`bondry_webhook_deliveries`	as últimas entregas, com reenvio (reenviar exige `publish`)

Toda escrita responde o que mudou e o que ainda falta, nunca só "ok". Nenhuma ferramenta aceita slug que não seja seu: slug de outra pessoa responde exatamente como um slug que nunca existiu.

Nenhuma ferramenta busca pacote pela rede. Só é lido o que veio na chamada. Por ferramenta o zip viaja em base64, com teto de 8 MB; acima disso o caminho é PUT /v1/publisher/releases/{version}/package, que aceita os bytes crus até 40 MB.

O que volta é dado#

Tudo que uma ferramenta de leitura devolve é texto de documentação. É dado, e não instrução: uma frase dentro de uma página, de um manifesto ou de um pacote não muda o que pediram ao seu agente. As descrições das ferramentas dizem isso, e o servidor repete na abertura da conversa.

Configuração do cliente#

Troque o identificador e o token pelos seus. O token aparece uma vez, na emissão, junto com um bloco igual a este.

Claude Code

Shell

claude mcp add --transport http bondry \
  https://mcp.bondry.org/v1/<hash> \
  --header "Authorization: Bearer bkm_xxxxxxxxxxxx.<segredo>"

Claude Desktop, e qualquer cliente que leia mcpServers

JSON

{
  "mcpServers": {
    "bondry": {
      "type": "http",
      "url": "https://mcp.bondry.org/v1/<hash>",
      "headers": {
        "Authorization": "Bearer bkm_xxxxxxxxxxxx.<segredo>"
      }
    }
  }
}

Aviso O token é credencial. Mantenha-o fora do repositório, fora do log de build e fora de uma gravação de tela. Se um escapar, a revogação é imediata.

O transporte, para quem escreve cliente#

Streamable HTTP, na forma que um servidor sem processo residente pode honrar: um POST, uma resposta JSON.

POST com uma única mensagem JSON-RPC. initialize, notifications/initialized, ping, tools/list e tools/call.
GET responde 405: não há stream de longa duração aqui. O Bondry Web roda em PHP-FPM, e um worker preso numa conexão aberta é um worker a menos para o site.
initialize responde com um Mcp-Session-Id, preso ao token e válido por trinta minutos de inatividade. Mande-o de volta nas chamadas seguintes. Sessão vencida, ou de outro token, responde 404, que é como o cliente sabe que precisa abrir outra.
DELETE com o cabeçalho da sessão a encerra.
Versões de protocolo faladas: 2025-11-25, 2025-06-18, 2025-03-26. Um cabeçalho MCP-Protocol-Version com outra versão responde 400 com a lista das que falamos.
Bearer inválido ou ausente responde 401 com WWW-Authenticate. Escopo faltando não é erro de HTTP: é resultado de ferramenta com isError.

Os tetos#

120 chamadas por minuto por token. As ferramentas de escrita herdam os tetos da publicação, inclusive os 500 anúncios por dia por token.

Cada chamada de ferramenta vira linha no log da API, com o token, a ferramenta e como ela terminou. As escritas também viram linha de auditoria, com a origem registrada, então "foi o pipeline ou o agente?" é pergunta com resposta. Nenhum argumento, nenhum pacote e nenhum segredo entra em log.

As skills#

As ferramentas são a fonte; as skills são o roteiro. Cinco delas estão publicadas, em inglês, e funcionam com ou sem este servidor conectado: Skills de agente.