Segurança do servidor MCP

Esta página foi escrita para a pessoa que precisa aprovar a conexão de um agente de IA ao Docsbook. Ela declara o que o servidor MCP realmente faz hoje — como um cliente se autentica, o que cada escopo pode acessar, o que é registrado, o que deixa a rede — e então identifica, em duas seções separadas, onde o Docsbook fica aquém da especificação do Model Context Protocol e quais artefatos de conformidade ainda não existem.

Nada aqui é aspiracional. Quando um controle está ausente, ele é listado como ausente.

O que você obtém#

Um cliente conectado mantém um único token Bearer opaco, vinculado a uma única conta do Docsbook e contendo um de dois escopos. O escopo é escolhido por uma pessoa em uma tela de consentimento — não solicitado pelo cliente. Toda ferramenta que atua em um projeto resolve esse projeto pelo proprietário, portanto um token que informa um ID de workspace pertencente a outra pessoa não recebe nada de volta, muito menos esse workspace: esse é o limite entre os locatários, e ele se aplica a todas as ferramentas.

O limite entre leitura e gravação é mais estreito do que os dois nomes de escopo sugerem, e a seção abaixo informa exatamente quais ferramentas o impõem e quais não. Leia-a antes de tratar um token somente leitura como uma medida de contenção.

Cada chamada contabilizada grava uma linha no próprio registro de chamadas do seu projeto: qual ferramenta foi usada, o que foi enviado, o que retornou, quanto tempo levou e o que consumiu. Os argumentos e resultados têm seus valores ocultados com base na chave antes de serem armazenados, portanto uma chave de API passada a uma ferramenta nunca é registrada.

O que você não obtém: expiração de token, tokens de atualização, limitação de taxa, funções dentro de uma conta ou um relatório de auditoria.

Como funciona a autenticação#

O fluxo de autorização#

O Docsbook é seu próprio servidor de autorização e seu próprio servidor de recursos. Ele emite tokens opacos para si mesmo; nunca aceita, encaminha ou reutiliza um token emitido por outra pessoa.

Os metadados publicados declaram um modelo de cliente público — code_challenge_methods_supported: ["S256"], token_endpoint_auth_methods_supported: ["none"], grant_types_supported: ["authorization_code"]. Não há segredo do cliente nem concessão de credenciais do cliente.

O que é o token#

O token consiste em 48 bytes provenientes do CSPRNG da plataforma, representados como 96 caracteres hexadecimais. Ele não contém declarações: é uma chave de consulta para uma linha que armazena a conta, o escopo e um registro de data e hora da revogação.

• Ele não expira. Nenhum expires_in é retornado e nenhum token de atualização é emitido. Um token é válido até ser revogado.
• A revogação é imediata. Revogar pelo painel registra a linha, e todas as chamadas subsequentes falham na consulta — não há cache à frente dela.
• Ele é armazenado como emitido, não com hash. Trate um token do Docsbook MCP como trataria uma senha: se a máquina que o armazena for comprometida, revogue-o em vez de presumir que ele expirou com o tempo. (O que é criptografado em repouso está listado em o que sai do seu espaço de trabalho.)
• O último uso é registrado em cada chamada, portanto um token não utilizado fica visível na lista de tokens do painel.

O que cada escopo pode fazer#

O escopo é uma única string comparada exatamente. Qualquer coisa que não seja o escopo de escrita é tratada como somente leitura — um valor não reconhecido falha de forma segura.

A verificação de escopo não abrange hoje todas as ferramentas de escrita, e você deve planejar levando isso em conta. Ela é aplicada exatamente a oito ferramentas: write_docs, create_issue, connect_source, configure_source, enable_agent e as três execuções de run_docs_* que fazem gravações. Essas ferramentas recusam um token somente leitura antes de fazer qualquer coisa.

Todas as outras ferramentas que alteram o estado — as ferramentas de escrita de configurações update_* e set_*, update_access, o registro e a remoção de webhooks, a criação de metas e funis, o envio, a aprovação e a exclusão de traduções, create_workspace — são controladas apenas pela propriedade do projeto, não pelo escopo. Portanto, um token somente leitura pode alterar as configurações de um projeto, ativar um webhook ou excluir uma tradução em um projeto que sua conta possua. Ele ainda não pode publicar uma página, abrir uma issue, conectar uma fonte ou ativar um agente.

Trate o escopo somente leitura como “não pode publicar nem configurar novas capacidades”, e não como “não pode alterar nada”. Se a contenção for mais importante do que isso, use uma conta Docsbook separada que possua apenas o projeto que você está disposto a expor. Isso é um defeito, listado novamente em limitações, não uma decisão de design.

Uma ferramenta que aplica a verificação responde a um token somente leitura com um erro estruturado READ_ONLY_TOKEN que identifica a ferramenta e informa como reautorizar — não um 403 simples nem uma operação silenciosa. O mesmo formato se aplica quando o saldo de um projeto está vazio (INSUFFICIENT_BALANCE, identificando o projeto, o preço e o restante) e quando um plano não inclui a capacidade (PLAN_RESTRICTION, identificando o nível).

O search anônimo é a única ferramenta sem token que lê um projeto, e seu acesso é recusado de três formas: em um endpoint fixado a nenhum projeto, em um projeto cuja visibilidade seja privada (o que também abrange um plano expirado) e quando não resta saldo no projeto para pagar pelo embedding da consulta. Ela não recebe nenhum argumento de projeto, portanto só pode ler o site ao qual está fixada.

O que um token não pode alcançar#

Cada ferramenta resolve seu workspace de destino a partir do workspace_id explícito, do argumento repo ou do próprio pin do endpoint — e, nos três casos, a consulta é filtrada pela conta do token. Um workspace que a conta não possui é resolvido como inexistente, e a ferramenta responde "workspace não encontrado". O resolvedor de faturamento aplica o mesmo filtro, portanto nomear o ID do projeto de outra pessoa também não permite debitar o saldo dela.

Vale mencionar mais dois limites, pois eles surpreendem algumas pessoas:

• write_docs faz commits no repositório hospedado pelo Docsbook usando as próprias credenciais do GitHub do Docsbook. Um site servido a partir de um repositório na sua própria conta do GitHub é recusado com NO_GITHUB_ACCESS, em vez de receber um commit. Portanto, um token MCP não é uma forma de fazer push para a sua organização do GitHub.
• Uma skill executada no modo de auditoria não pode fazer alterações. Enquanto uma skill no modo audit estiver ativa, uma lista explícita de ferramentas de escrita, além de toda ferramenta cujo nome comece com update_, set_, register_webhook_, enable_ ou disable_, é recusada antes de ser executada. run_docs_analyze define esse modo para toda a sua execução, razão pela qual é seguro usá-lo com um token somente leitura.

O que é registrado#

Cada chamada MCP — tarifada ou não, bem-sucedida ou não — grava uma linha no registro de chamadas do projeto, e o proprietário do projeto pode lê-la no painel Feeds.

Dois detalhes da remoção de dados sensíveis são importantes para a revisão. Ela verifica a chave, sem distinção entre maiúsculas e minúsculas e como uma substring, não o formato do valor — tentar adivinhar a aparência de um segredo deixa passar os casos que não correspondem ao formato esperado. E ela é executada tanto na saída quanto na entrada, portanto uma ferramenta que repete sua própria entrada não pode vazar uma chave por meio do resultado. Cada lado é limitado a 8 000 caracteres, com um marcador informando quantos foram removidos.

As análises no nível do leitor nunca transmitem uma identidade a um cliente MCP. Um visitante é um pseudônimo: sha256(salt | repository | ip), truncado para 16 caracteres hexadecimais, com o salt mantido no servidor. get_top_visitors, get_page_journeys e get_visitor_activity retornam esse pseudônimo, um país e eventos no nível da página; nenhuma ferramenta retorna um endereço IP, um nome ou um e-mail. O pseudônimo tem escopo de um único repositório, portanto o mesmo leitor em dois dos seus sites corresponde a dois IDs não relacionados.

O que sai do seu espaço de trabalho#

Duas afirmações que a página de segurança de um fornecedor de documentação costuma fazer, corrigidas:

• "Seu conteúdo nunca sai do seu repositório" não é verdade aqui. O Docsbook armazena uma cópia pesquisável do texto das suas páginas e de suas incorporações vetoriais, e envia o texto das páginas a um provedor de modelos para criar essas incorporações e responder a chamadas de chat e de agentes. O que é verdade é que o GitHub continua sendo a fonte da verdade, portanto interromper o pagamento interrompe o trabalho medido sem excluir seu Markdown.
• As buscas externas são protegidas, não meramente confiadas. Antes de qualquer busca, o esquema é verificado, o hostname é resolvido e um endereço resolvido em um intervalo privado ou reservado é recusado — e a verificação é executada novamente a cada salto de redirecionamento, para que uma URL pública não possa redirecionar para uma URL interna. robots.txt é respeitado e a resposta é limitada. O buscador de habilidades é ainda mais restrito: ele só buscará no próprio host e no prefixo de caminho do catálogo, portanto não pode ser transformado em um proxy de URL arbitrária.

Webhooks e hooks de chat não são a mesma coisa#

As entregas de webhooks de saída são assinadas. A assinatura é HMAC-SHA256 sobre os bytes exatos enviados, em X-Docsbook-Signature-256: sha256=<hex>, juntamente com X-Docsbook-Event. Uma URL de incoming webhook do Discord ou do Slack é adaptada para essa plataforma antes da assinatura, portanto a assinatura sempre abrange o que seu endpoint realmente recebe. O segredo é definido no registro, tem pelo menos 16 caracteres e nunca mais é retornado em texto simples. As tentativas de entrega expiram após 15 segundos, e a resposta é armazenada truncada.

Os hooks de chat não carregam nenhuma assinatura. Os hooks de pré, pós e streaming do assistente de documentação são POSTs JSON simples, com um tempo limite de 5 segundos e sem cabeçalho HMAC. Não reutilize seu código de verificação de webhook nesse caso nem presuma que ele verificou alguma coisa. O pré-hook também pode retornar inject_context, cujo texto entra no prompt do assistente — portanto, um endpoint para o qual você aponta um hook de chat pode influenciar o que o assistente diz; trate-o como infraestrutura confiável, autentique-o de alguma outra forma e não aponte um hook para uma URL que você não controla.

Por que esta é a maneira correta (evidências)#

Há mais um ponto que cabe ao seu cliente, e não a nós: a especificação do MCP orienta os clientes a "considerar as anotações de ferramentas não confiáveis, a menos que venham de servidores confiáveis" e a manter "um humano no circuito com capacidade de negar invocações de ferramentas" (Ferramentas do MCP). Um token do Docsbook com leitura e escrita é exatamente o caso que merece esse humano.

Onde o Docsbook não atende hoje à especificação do MCP#

Estas são avaliadas em relação à revisão 2026-07-28. Cada uma representa uma lacuna no Docsbook, não uma discordância em relação à especificação.

O que o Docsbook ainda não tem#

Listado para que uma revisão possa excluir o Docsbook numa hora, em vez de na terceira semana.

Uma capacidade é frequentemente confundida com a segunda e a quarta linhas: um espaço de trabalho privado pode ser protegido por uma palavra-passe ou pelo seu próprio fornecedor OIDC através de update_access, em qualquer plano. Isto é início de sessão único para os leitores do seu site de documentação. Não é início de sessão único para os membros da sua conta Docsbook e não concede acesso MCP.

Se a sua organização precisar de um artefacto específico — um DPA ao abrigo do RGPD, um BAA, um questionário preenchido — escreva para support@docsbook.io e pergunte o que existe. A resposta hoje pode muito bem ser que não existe.

Limites e questões em aberto#

• Regiões de hospedagem: uma questão em aberto. Esta página deliberadamente não nomeia nenhuma região para o banco de dados ou o armazenamento analítico. Ambos são serviços gerenciados cuja região é uma configuração de implantação, e não algo que um leitor possa verificar pelo comportamento do Docsbook; além disso, uma versão anterior desta página nomeava regiões sem indicar uma fonte. Se a residência dos dados fizer parte da sua análise, peça ao suporte a resposta atual por escrito.
• O ID pseudônimo do visitante é um pseudônimo, não uma anonimização. Trata-se de um hash com salt de um endereço IP truncado para 64 bits. Qualquer pessoa que tenha o salt e o armazenamento bruto de eventos poderá derivá-lo novamente; a garantia é que o salt não está nos dados e nenhuma API retorna um IP. Cabe ao seu órgão regulador decidir se isso atende aos requisitos aplicáveis.
• Um token de leitura e gravação é uma credencial administrativa completa. Não há como conceder "pode editar páginas, mas não pode alterar configurações" ou "pode ler análises, mas não transcrições de chat". A hierarquia de escopos tem dois níveis.
• O escopo somente leitura é aplicado de forma incompleta. Oito ferramentas o verificam; as ferramentas de configurações, webhook, metas e tradução não o fazem, e as descrições de algumas dessas próprias ferramentas afirmam que exigem um token de leitura e gravação, embora nada faça essa verificação. Até que isso seja corrigido, o limite confiável é a propriedade da conta, não o escopo — portanto, isole por conta e consulte a lista aplicada acima em vez da descrição de uma ferramenta.
• Nada aqui foi atestado de forma independente. Cada afirmação acima pode ser verificada no comportamento do Docsbook — emita um token somente leitura e observe uma ferramenta de gravação recusá-lo; conecte um projeto que você não possui e observe que ele não é resolvido —, mas nenhum terceiro o auditou. Trate esta página como uma especificação que você pode testar, não como uma certificação.
• A disponibilidade e o preço estão na página de preços. Nenhum valor é citado aqui, porque um preço copiado para a documentação fica desatualizado silenciosamente.

Relacionado#

• Servidor MCP — as próprias ferramentas e em que uma chamada se baseia
• Conteúdo pronto para agentes — as quatro interfaces de máquina e como elas se integram
• Habilidades de documentação — o que uma habilidade pode e não pode fazer durante sua execução
• Webhooks — o esquema completo de eventos e a verificação de assinatura
• Ganchos de chat de IA — os ganchos não assinados de pré, pós e streaming
• Fontes — o que um agente tem permissão para ler em seu nome